Theming

createTheme deep-merges your overrides onto the Bootstrap defaults and produces a full theme object. Pass it to the provider and every component re-skins at once.

createTheme

createTheme(overrides) takes a DeepPartial<Theme> — you only specify what you want to change, and everything else falls back to the Bootstrap 5.3 defaults. It returns a complete Theme you hand to the provider.

tsx

import { BootstrapStyledProvider, createTheme } from '@metatoy/bootstrap-styled';

const theme = createTheme({
colors: { primary: '#6e2c92' },
colorRgb: { primary: '110, 44, 146' },
radius: { base: '0.5rem' },
});

export default function App() {
return (
  <BootstrapStyledProvider theme={theme}>
    <App />
  </BootstrapStyledProvider>
);
}

The merge is recursive, so nested overrides don’t require the surrounding object — set radius.base without restating the other radii. Derived values are recomputed for you: change colors.primary and the readable text color on primary buttons (--bs-primary-contrast) is recalculated automatically, and --bs-link-color follows primary too.

Live re-skin

The demo below renders real components inside a provider whose theme is built with createTheme. Toggle between the Bootstrap default and a custom purple theme — the buttons, badge, alert, and link color all move together:

Because the primary color flows through the --bs-primary token that these components read, a single colors.primary override re-skins all of them — no per-component styling.

What you can theme

createTheme accepts overrides for the entire token surface. The most common fields:

Field	Controls
colors	The eight contextual colors (`primary`…`dark`).
colorRgb	The `r, g, b` triplets used for opacity utilities (`—bs-primary-rgb`).
colorTokens	Per-color `bgSubtle` / `borderSubtle` / `emphasis` tints.
radius	Border radii (`sm`, `base`, `lg`, `pill`, …).
spacing	The Bootstrap spacing scale (indexes 0–5).
font	Font families, sizes, weights, line heights, heading scale.
border · shadow · zIndex	Borders, elevation, and stacking order.
dark	The token values that override under `[data-bs-theme=dark]` — see Color modes.

Keep RGB in sync

Bootstrap exposes an --bs-<color>-rgb triplet for each color so opacity utilities can build rgba() values. When you override a color, set the matching colorRgb entry too so translucent backgrounds and borders track your new color:

tsx

createTheme({
colors:   { primary: '#6e2c92' },
colorRgb: { primary: '110, 44, 146' },
});

Runtime vs. build-time

The theme object is applied at render, so you can swap it at runtime — hold it in state and pass a different theme to re-skin live. For scoped or one-off overrides that don’t need a new theme object, set the CSS variables directly.