HammerHammer

Theme Switch

A control that switches between light, dark and system color themes.

Open in v0

Last updated:07/10/2026, 05:52:32

pnpm dlx shadcn add @chaos-design/theme-switch
npx shadcn@latest add @chaos-design/theme-switch
yarn dlx shadcn add @chaos-design/theme-switch
bunx shadcn add @chaos-design/theme-switch
Open preview in new tab

Every option

Each prop of ThemeSwitch has a card of its own. Open a switch's menu, or use the buttons on the controlled card.

Open preview in new tab

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 value supplied the component still applies the theme to the document, but it no longer persists to localStorage nor syncs its siblings.
  • attribute is document-wide. With data-theme the component writes that attribute and removes the .dark class, 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-switch

Usage

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

PropTypeDefaultDescription
valueTheme-Controlled theme ('light' | 'dark' | 'system').
defaultThemeTheme'system'Theme used when nothing is stored.
onValueChange(theme: Theme) => void-Called when the user picks a theme.
storageKeystring'theme'Storage key used by the persisted theme.
enableSystembooleantrueWhether to offer the System entry.
attribute'class' | 'data-theme''class'How the theme is written to the document root.
disableTransitionOnChangebooleantrueDisable CSS transitions while swapping themes.
labelsPartial<Record<Theme, string>>-Customize item text (i18n).
iconsPartial<Record<Theme, ComponentType>>-Customize item icons.
triggerLabelstring-aria-label for the trigger.
classNamestring-Custom class name for the trigger.
classNamesThemeSwitchClassNames-Per-slot class overrides.

ThemeSwitchClassNames

PropDescription
triggerThe trigger button.
contentThe floating menu.
itemMenu items.
iconIcons.

On this page