Skip to content

Components · Reference

Theme Switcher

A localStorage-persisted light, dark, and system theme switcher with a ScriptOnce startup script to avoid theme flash.

Last updated September 28, 2026

Overview

theme-switcher provides a compact dropdown for switching between light, dark, and system themes. It persists the selected theme in localStorage, applies the resolved theme class to the document element, and renders a ScriptOnce startup script from ThemeProvider to avoid theme flash. Labels are stored in the component file and can be overridden with the messages prop.

Set the active locale once with KrakstackProvider; pass locale directly only when a component needs an override. Message overrides are keyed by arbitrary locale strings, so additional languages can be supplied with messages={{ es: { ... } }}. Exact locale keys such as es-MX take precedence over base keys such as es; English is the final fallback.

Install

shell
bunx shadcn@latest add @krak-stack/theme-switcher

Usage

Wrap your app in ThemeProvider.

tsx
import { ThemeProvider } from "@/components/ui/theme-switcher";

<ThemeProvider>{children}</ThemeProvider>

Render the switcher from a component inside the provider.

tsx
import { ThemeSwitcher, useTheme } from "@/components/ui/theme-switcher";

const { theme, setTheme } = useTheme();

<ThemeSwitcher locale={locale} value={theme} onChange={setTheme} />

<ThemeSwitcher
  value={theme}
  onChange={setTheme}
  locale={locale}
  messages={{ [locale]: { title: "Theme", light: "Day", dark: "Night" } }}
/>
Dependencies
Packages and shadcn components required by this registry item.

Dependencies

Registry Dependencies