ThemeProvider
ThemeProvider ships the kovax-react design tokens as CSS variables, manages light/dark modes, and lets you brand the whole tree (or a single subtree) without forking components.
Quick start
Wrap your app once. Every component that uses themeToken() (which is all of them) now reads its values from a single source of truth.
Once the provider is mounted, switching colorMode instantly re-themes every descendant — no re-render of business code needed.
Reacting to color mode
useColorMode() returns the active mode plus stable setters. Use it for theme toggles, persisted preferences, or coordinating third-party widgets.
colorMode reflects the user's choice; resolvedColorMode is always "light" or "dark" (system → resolved through prefers-color-scheme).
colorMode: light
resolvedColorMode: light
Scoped themes
Pass a ref to target. The provider writes data-kovax-theme on that element only, so you can render a dark widget in an otherwise light page (or vice versa).
Light island
Locked to the light palette regardless of the global mode.
Dark island
Locked to the dark palette — perfect for product hero blocks or media surfaces.
Custom brand palette
Provide partial overrides via the palettes prop. Anything you don't set falls back to the built-in light/dark palette.
Tap the button to swap primary for a custom purple ramp inside this card only.
Branded primary text
Inspecting the active palette
useTheme() exposes the full context — useful for design tooling, palette previews, or driving third-party libraries with the right colors.
These swatches are read live from useTheme().palette. They change whenever the active color mode flips.
primary.500#3b82f6secondary.50#f8fafcsecondary.900#0f172asuccess.500#10b981warning.500#f59e0berror.500#ef4444Reading tokens from your own components
themeToken("…") returns a var(--kx-…, fallback) string. It works inside CSS-in-JS, plain style props, and even server-rendered HTML — the fallback keeps things looking correct before hydration.
This card composes themeToken calls for background, color, padding, shadow and transition. Flip the global mode in the header to watch it animate.
Server-side rendering
ThemeProvider is SSR-safe. Render it on the server with a known defaultColorMode (or read a cookie) to avoid a hydration flash. Use storageKey={false} on isolated trees you don't want persisted.
On the server we render with defaultColorMode="light" (or whatever you store in a cookie) so the first paint matches the user's last choice — no flash, no layout shift.
Props
| Prop | Type | Description |
|---|---|---|
colorMode | "light" | "dark" | "system" | Controlled mode. When provided, the provider ignores internal state and storage — drive it from your own store. |
defaultColorMode | "light" | "dark" | "system" | Initial uncontrolled mode. Defaults to "system". |
onColorModeChange | (mode, resolved) => void | Fires after every effective mode change (including system resolution flips). Use it to sync analytics, cookies, or remote prefs. |
storageKey | string | false | null | localStorage key for persistence. Pass false or null to disable (e.g. inside scoped providers). |
palettes | { light?: Partial<ThemePalette>; dark?: Partial<ThemePalette> } | Partial overrides per side. Merged on top of the built-in light/dark palettes (color ramps, base colors, shadows). |
target | "documentElement" | RefObject<HTMLElement> | Element that receives the data-kovax-theme attribute. Defaults to documentElement; pass a ref to scope theming to a subtree. |
nonce | string | nonce attribute forwarded to the injected <style>. Required when running under a strict Content-Security-Policy. |