Customize

Customization happens in three layers, from global to local: the theme object, the —bs-* CSS variables, and per-instance className / style passthrough. Reach for the smallest one that does the job.

The three layers

Layer	Scope	Use it for
Theme object	Whole app (per provider)	Brand colors, radii, spacing, fonts — your design system.
—bs-* variables	Any subtree (CSS cascade)	Scoped overrides and runtime tweaks without re-rendering.
className / style	A single instance	One-off adjustments to one component.

1. Theme object — global design tokens

Pass a theme built with createTheme to the provider. It deep-merges your overrides onto the Bootstrap defaults and emits the whole --bs-* surface, so one object re-skins the entire app.

tsx

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

const theme = createTheme({ colors: { primary: '#6e2c92' } });

<BootstrapStyledProvider theme={theme}>
<App />
</BootstrapStyledProvider>;

2. CSS variables — scoped and runtime

Every component reads Bootstrap’s --bs-* custom properties. Set one on any element and it cascades to that subtree only — no provider, no re-render. This is also how dark mode works internally.

tsx

<div style={{ '--bs-primary': '#d63384' }}>
<Button variant="primary">Pink here only</Button>
</div>

3. className / style — one instance

Every component forwards className and style to its root element, so styled-components, CSS Modules, or a plain inline style can adjust a single instance:

tsx

<Button variant="primary" className="my-cta" style={{ borderRadius: 999 }}>
Rounded
</Button>

Which layer to reach for

Changing your brand or design tokens across the app → the theme object.
A section that needs different colors, or a runtime tweak → CSS variables.
One component that needs a nudge → className / style.

Continue to Theming for the theme object, or CSS variables for the variable surface.