Theme Switcher

Choose system, light, or dark with a moving selection surface.

Examples

Theme transition

A slide transition declared on this control. Duration is 500 milliseconds. Other controls keep their own settings.

Shadow borders

Use a prominent ambient shadow and inset edge in place of a solid border.

When to use

Show all three appearance choices in a header or settings row.
Use a moving selection surface to connect the old and new choice.

When not to use

Space permits only one compact action. Use Icon Theme Toggle.
People need a longer list of named choices. Use Theme Selector.

Installation

Set up uitheme-web in an existing Tailwind app. Then install the component. The CLI copies one component file and reuses the shared cn utility.

Tailwind version

Source language

npx uitheme-cli add theme-switcher --base base-ui --tailwind 4 --language ts

To install with shadcn, first add the UI-Theme registry to components.json. The style in components.json selects Radix or Base UI.

npx shadcn@latest add @uitheme/theme-switcher

Usage

Use the control inside your theme provider. Import it from your app’s component directory.

example.tsx

'use client';

import { UIThemeProvider } from 'uitheme-web/react';
import { ThemeSwitcher } from '@/components/ui/theme-switcher';

export function Example() {
  return (
    <UIThemeProvider>
      <ThemeSwitcher />
    </UIThemeProvider>
  );
}

API reference

These props belong to the installed control. Its page transition settings override the provider for this action only.

Prop	Type	Behavior
`label`	`string`	Override the readable accessible label.
`borderStyle`	`'solid' \| 'shadow'`	Use the default solid border or prominent shadow borders. Both use the same space and theme tokens.
`className`	`string`	Extend the root styles. Your classes replace default classes through the local merge helper.
`classes`	`object`	Style root, item, and selection indicator parts.
`disabled`	`boolean`	Disable interaction. Preference controls also wait for the provider to mount.
`animationType`	`ThemeAnimationType`	Override the UI theme transition for this control. Defaults to the provider setting.
`duration`	`number`	UI theme transition duration in milliseconds. Defaults to the provider setting.
`slideDirection`	`SlideDirection`	Valid only with animationType set to ThemeAnimationType.SLIDE. Other animation types do not accept this prop.

Keyboard

Key	Action
Tab	Enter or leave the radio group.
Arrow keys	Move and select among enabled choices.
Space	Select the focused radio.

Accessibility

Keep the accessible label when changing the visible content. Icons are decorative.
The control stays disabled until the theme provider mounts.
Reduced motion removes travel and rotation. Icon state keeps a short opacity change. The selection surface changes position without travel.
Keyboard activation changes the theme without the pointer animation.

The checked radio follows the stored theme preference, including system. The selected surface moves between the three equal tracks. The icons brighten on fine-pointer hover. The group disables choices that the provider does not support.

AI Agent notes

Use uitheme-web/react for React or uitheme-web/vue for Vue. Keep the theme provider around the control.
Keep page transitions in the control’s animationType and duration props. Do not add a standalone transition-settings control.
Keep input labels, focus styles, selected state, disabled state, and reduced-motion behavior when editing source.
Use the shared theme tokens. Do not hardcode a palette or radius.

Source

The CLI reuses your shared cn utility. If it is missing, installation creates it at the configured utils path. Existing utilities are checked before a replacement is offered.

These are the files the CLI installs. The control installs one main component file.

'use client';

import * as React from 'react';
import { useUITheme, type Theme } from 'uitheme-web/react';
import { SunIcon, MoonIcon, MonitorIcon } from 'lucide-react';
import { cn } from '@/lib/utils';
import type { ThemeControlTransitionProps } from 'uitheme-web/react';

export type ThemeSwitcherProps = ThemeControlTransitionProps & {
  label?: string;
  disabled?: boolean;
  borderStyle?: 'solid' | 'shadow';
  className?: string;
  classes?: {
    root?: string;
    item?: string;
    indicator?: string;
  };
};

const choices: readonly Theme[] = ['system', 'light', 'dark'];

export function ThemeSwitcher({
  label = 'Theme',
  disabled = false,
  animationType,
  duration,
  slideDirection,
  borderStyle = 'solid',
  className,
  classes,
}: ThemeSwitcherProps) {
  const { theme, themes, mounted, switchTheme } = useUITheme();
  const id = React.useId();
  const [keyboard, setKeyboard] = React.useState(false);

  return (
    <div
      role="radiogroup"
      aria-label={label}
      onKeyDownCapture={() => setKeyboard(true)}
      onPointerDownCapture={() => setKeyboard(false)}
      className={cn(
        'relative isolate inline-grid h-8 shrink-0 grid-cols-3 items-stretch rounded-[var(--radius)] border border-border bg-muted p-[var(--switcher-pad)] [--switcher-pad:calc(var(--spacing,0.25rem)/2)] [--switcher-inner-radius:max(0px,calc(var(--radius)-var(--switcher-pad)-1px))] [@media(pointer:coarse)]:h-11',
        'data-[border-style=shadow]:[--shadow-border-edge:theme(colors.border)] data-[border-style=shadow]:[--shadow-border-focus:theme(colors.ring)] data-[border-style=shadow]:border-transparent data-[border-style=shadow]:focus-visible:border-transparent data-[border-style=shadow]:ring-0 data-[border-style=shadow]:focus-visible:ring-0 data-[border-style=shadow]:shadow-[0_0_4px_rgb(0_0_0_/_0.25),inset_0_0_0_1px_var(--shadow-border-edge)] data-[border-style=shadow]:forced-colors:outline data-[border-style=shadow]:forced-colors:outline-1 data-[border-style=shadow]:forced-colors:outline-[CanvasText] data-[border-style=shadow]:forced-colors:focus-visible:outline-2 data-[border-style=shadow]:forced-colors:focus-visible:outline-[Highlight]',
        classes?.root,
        className
      )}
      data-border-style={borderStyle}
    >
      <span
        aria-hidden="true"
        data-slot="selection-indicator"
        style={{ transform: `translateX(${choices.indexOf(theme) * 100}%)` }}
        className={cn(
          'pointer-events-none absolute bottom-[var(--switcher-pad)] left-[var(--switcher-pad)] top-[var(--switcher-pad)] -z-10 w-[calc((100%_-_var(--switcher-pad)_-_var(--switcher-pad))/3)] rounded-[var(--switcher-inner-radius)] bg-card border border-border motion-reduce:transition-none',
          keyboard
            ? 'transition-none'
            : 'transition-transform duration-200 ease-[cubic-bezier(0.22,1,0.36,1)]',
          classes?.indicator
        )}
      />
      {choices.map((value) => (
        <label
          key={value}
          data-checked={theme === value ? '' : undefined}
          className={cn(
            'relative flex min-w-8 cursor-pointer items-center justify-center rounded-[var(--switcher-inner-radius)] px-2 text-muted-foreground has-[:disabled]:cursor-not-allowed has-[:disabled]:opacity-50 has-[:focus-visible]:ring-[3px] has-[:focus-visible]:ring-ring/50 data-[checked]:text-foreground [@media(hover:hover)_and_(pointer:fine)]:hover:text-foreground [@media(pointer:coarse)]:min-w-11',
            keyboard
              ? 'transition-none'
              : 'transition-colors duration-150 ease-[cubic-bezier(0.22,1,0.36,1)]',
            classes?.item
          )}
        >
          <input
            type="radio"
            name={id}
            value={value}
            checked={theme === value}
            aria-label={`${value[0]!.toUpperCase() + value.slice(1)} theme`}
            disabled={disabled || !mounted || !themes.includes(value)}
            className="peer absolute inset-0 z-10 m-0 size-full cursor-inherit opacity-0"
            onChange={(event) =>
              void switchTheme(value, {
                animationType,
                duration,
                slideDirection,
                animationOff: keyboard,
                element: event.currentTarget.closest('label'),
              })
            }
          />
          {React.createElement(
            value === 'light'
              ? SunIcon
              : value === 'dark'
                ? MoonIcon
                : MonitorIcon,
            { 'aria-hidden': true, className: 'size-4 shrink-0' }
          )}
        </label>
      ))}
    </div>
  );
}

Dependencies: lucide-react

Customization

Use borderStyle="shadow" in React or border-style="shadow" in Vue for prominent shadow borders. The default is solid.

Use slideDirection only when animationType is ThemeAnimationType.SLIDE. Set both props on the control when you need a slide direction override.

Theme Switcher

Preview

Examples

Theme transition

Shadow borders

When to use

When not to use

Installation

Usage

API reference

Keyboard

Accessibility

Theme behavior

AI Agent notes

Source

Customization

PreviewCopy Anchor Link

ExamplesCopy Anchor Link

Theme transition

Shadow borders

When to useCopy Anchor Link

When not to useCopy Anchor Link

InstallationCopy Anchor Link

UsageCopy Anchor Link

API referenceCopy Anchor Link

KeyboardCopy Anchor Link

AccessibilityCopy Anchor Link

Theme behaviorCopy Anchor Link

AI Agent notesCopy Anchor Link

SourceCopy Anchor Link

CustomizationCopy Anchor Link

Preview

Examples

When to use

When not to use

Installation

Usage

API reference

Keyboard

Accessibility

Theme behavior

AI Agent notes

Source

Customization