Theme Switch
A control that switches between light, dark and system color themes.
pnpm dlx shadcn add @chaos-design/theme-switchnpx shadcn@latest add @chaos-design/theme-switchyarn dlx shadcn add @chaos-design/theme-switchbunx shadcn add @chaos-design/theme-switchEvery option
Each prop of ThemeSwitch has a card of its own. Open a switch's menu, or use the buttons on the controlled card.
Three behaviours worth knowing:
- Uncontrolled switches move together. They sync through a module-level broadcast, so changing the theme once moves all eight cards.
- A controlled switch writes nothing. With
valuesupplied the component still applies the theme to the document, but it no longer persists tolocalStoragenor syncs its siblings. attributeis document-wide. Withdata-themethe component writes that attribute and removes the.darkclass, so your CSS has to match[data-theme="dark"]:
<ThemeSwitch attribute="data-theme" />[data-theme="dark"] {
/* your dark variables */
}Installation
npm install @chaos-design/theme-switchUsage
import { ThemeSwitch } from '@chaos-design/theme-switch';
export default function Demo() {
return <ThemeSwitch />;
}Pair it with the blocking script (rendered into <head> on the server) so the theme is already applied before the first paint:
import { ThemeScript } from '@chaos-design/theme-switch';
export default function Root() {
return (
<html lang="en" suppressHydrationWarning>
<head>
<ThemeScript />
</head>
<body>{/* ... */}</body>
</html>
);
}Props
| Prop | Type | Default | Description |
|---|---|---|---|
| value | Theme | - | Controlled theme ('light' | 'dark' | 'system'). |
| defaultTheme | Theme | 'system' | Theme used when nothing is stored. |
| onValueChange | (theme: Theme) => void | - | Called when the user picks a theme. |
| storageKey | string | 'theme' | Storage key used by the persisted theme. |
| enableSystem | boolean | true | Whether to offer the System entry. |
| attribute | 'class' | 'data-theme' | 'class' | How the theme is written to the document root. |
| disableTransitionOnChange | boolean | true | Disable CSS transitions while swapping themes. |
| labels | Partial<Record<Theme, string>> | - | Customize item text (i18n). |
| icons | Partial<Record<Theme, ComponentType>> | - | Customize item icons. |
| triggerLabel | string | - | aria-label for the trigger. |
| className | string | - | Custom class name for the trigger. |
| classNames | ThemeSwitchClassNames | - | Per-slot class overrides. |
ThemeSwitchClassNames
| Prop | Description |
|---|---|
| trigger | The trigger button. |
| content | The floating menu. |
| item | Menu items. |
| icon | Icons. |