Skip to content

Theme Selector

Choose light, dark, or the system appearance.

Preview

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.

Icon with text

Show an icon beside the theme label.

When to use

  • Let people choose light, dark, or system appearance in app settings.

  • Show the appearance options configured on the provider in one labeled control.

  • Use the floating menu in headers, toolbars, and compact layouts.

When not to use

  • A toolbar needs only a quick light/dark action. Use Theme Toggle.
  • The choice changes brand colors rather than appearance. Use Color Theme Selector.

Installation

Set up uitheme-web in an existing Tailwind app. Then install the component.

Tailwind version
Source language
npx uitheme-cli add theme-selector --base radix --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-selector

Usage

Use the component inside your theme provider. Use import paths that match your app’s component directory.

example.tsx
'use client';

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

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

For inline choices, install Theme Disclosure. The floating selector does not install disclosure code.

API reference

These props belong to the installed local control. Configure theme options on the provider.

PropTypeBehavior
labelstringOverride the readable accessible label.
borderStyle'solid' | 'shadow'Use the default solid border or prominent shadow borders. Both use the same space and theme tokens.
classNamestringExtend the root styles. Your classes replace default classes through the local merge helper.
classesobjectStyle root, trigger, content, item, and label parts.
disabledbooleanDisable interaction. Preference controls also wait for the provider to mount.
animationTypeThemeAnimationTypeOverride the UI theme transition for this control. Defaults to the provider setting.
durationnumberUI theme transition duration in milliseconds. Defaults to the provider setting.
slideDirectionSlideDirectionValid only with animationType set to ThemeAnimationType.SLIDE. Other animation types do not accept this prop.
display'text' | 'icon-text'Use text by default, or an icon with text. For an icon-only action, use Icon Theme Toggle. Light uses a sun, dark uses a moon, and system uses a monitor.

Keyboard

KeyAction
Enter / SpaceOpen the selector or confirm the focused option.
Arrow keysMove between available appearance options.
EscapeClose the menu and return focus to the trigger.

Accessibility

  • Keep the label connected to the trigger. Preserve the primitive’s focus behavior.
  • The option list comes from the provider. Avoid showing a system option when that option is not configured.

Theme behavior

  • Use theme for the selected preference. System stays selected when the operating system changes appearance.
  • Changes use switchTheme. The trigger sets the transition origin. The color palette does not change.

AI Agent notes

Use this checklist when a coding agent adds the control.

  • Use uitheme-web/react for the runtime. Import the control from its installed local file. The runtime does not export styled controls.
  • For Next.js, use NextUIThemeProvider from uitheme-web/next. For TanStack Start, follow the server bootstrap guide. Create server state for each request.
  • Before installation, select the framework, primitive base, Tailwind major version, and language. Run the CLI inside the app or pass --cwd.
  • Preview changes with --dry-run. Keep edited local files. Review the differences before using --overwrite.
  • Read the provider’s themes array. Show only the options configured on the provider.
  • Use theme for the selected value. Use resolvedTheme for visual appearance.
  • Check keyboard controls in the running app. Check that appearance and palette choices survive a reload. Check reduced motion.

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 component source stays in your app.

'use client';

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

export type ThemeSelectorClasses = {
  root?: string;
  trigger?: string;
  content?: string;
  item?: string;
  label?: string;
};

export type ThemeSelectorProps = ThemeControlTransitionProps & {
  display?: 'text' | 'icon-text';
  borderStyle?: 'solid' | 'shadow';
  className?: string;
  classes?: ThemeSelectorClasses;
  label?: string;
  disabled?: boolean;
};

export const ThemeSelector = React.forwardRef<
  HTMLButtonElement,
  ThemeSelectorProps
>(function ThemeSelector(
  {
    animationType,
    duration,
    slideDirection,
    borderStyle = 'solid',
    display = 'text',
    className,
    classes,
    label = 'Theme',
    disabled = false,
  }: ThemeSelectorProps,
  forwardedRef
) {
  const { theme, themes, mounted, switchTheme } = useUITheme();
  const triggerRef = React.useRef<HTMLButtonElement>(null);
  const id = React.useId();
  const selected = theme;

  const options: {
    value: string;
    label: string;
  }[] = themes.map((value) => ({
    value,
    label: value
      .replaceAll('-', ' ')
      .replace(/\b\w/g, (letter) => letter.toUpperCase()),
  }));

  React.useImperativeHandle(forwardedRef, () => triggerRef.current!);

  const change = (
    value: string,
    element: HTMLElement | null = triggerRef.current
  ) => {
    const next = themes.find((theme) => theme === value);

    if (next)
      void switchTheme(next, {
        element,
        animationType,
        duration,
        slideDirection,
      });
  };

  return (
    <div className={cn('flex flex-col gap-2', classes?.root, className)}>
      <Select.Root
        value={selected}
        disabled={disabled || !mounted}
        onValueChange={(next) => void change(next)}
      >
        <label
          htmlFor={id}
          className={cn('text-sm font-medium text-foreground', classes?.label)}
        >
          {label}
        </label>
        <Select.Trigger
          ref={triggerRef}
          id={id}
          disabled={disabled || !mounted}
          className={cn(
            'flex h-10 w-full min-w-0 items-center justify-between gap-2 rounded-[var(--radius)] border border-border bg-background px-3 py-2 text-sm text-foreground outline-none transition-[color,box-shadow,border-color] hover:bg-accent/40 focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 motion-reduce:transition-none',
            '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] data-[border-style=shadow]:hover:shadow-[0_0_4px_rgb(0_0_0_/_0.25),inset_0_0_0_1px_color-mix(in_oklch,var(--shadow-border-focus)_55%,transparent)] data-[border-style=shadow]:focus-visible:shadow-[0_0_12px_color-mix(in_oklch,var(--shadow-border-focus)_18%,transparent),0_1px_3px_rgb(0_0_0_/_0.1),inset_0_0_0_2px_color-mix(in_oklch,var(--shadow-border-focus)_55%,transparent)]',
            classes?.trigger
          )}
          data-border-style={borderStyle}
        >
          <span className="flex min-w-0 items-center gap-2">
            {display !== 'text' &&
              React.createElement(
                selected === 'light'
                  ? SunIcon
                  : selected === 'dark'
                    ? MoonIcon
                    : MonitorIcon,
                { 'aria-hidden': true, className: 'size-4 shrink-0' }
              )}
            <Select.Value className="min-w-0 truncate text-left" />
          </span>
          <Select.Icon asChild>
            <ChevronDownIcon
              aria-hidden="true"
              className="size-4 shrink-0 text-muted-foreground"
            />
          </Select.Icon>
        </Select.Trigger>
        <Select.Portal>
          <Select.Content
            position="popper"
            sideOffset={6}
            align="start"
            className={cn(
              'z-50 min-w-[max(10rem,var(--radix-select-trigger-width))] max-h-[min(20rem,var(--radix-select-content-available-height,20rem))] overflow-y-auto overscroll-contain rounded-[var(--radius)] border border-border bg-popover p-1 text-popover-foreground shadow-md outline-none [scrollbar-width:thin]',
              '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?.content
            )}
            data-border-style={borderStyle}
          >
            <Select.Viewport>
              {options.map((option) => (
                <Select.Item
                  key={option.value}
                  value={option.value}
                  className={cn(
                    'relative flex min-h-9 w-full cursor-default select-none items-center gap-2 rounded-[max(0px,calc(var(--radius)-4px))] py-2 pl-3 pr-9 text-sm outline-none data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[selected]:bg-accent/60 data-[state=checked]:bg-accent/60 data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
                    classes?.item
                  )}
                >
                  {display !== 'text' &&
                    React.createElement(
                      option.value === 'light'
                        ? SunIcon
                        : option.value === 'dark'
                          ? MoonIcon
                          : MonitorIcon,
                      { 'aria-hidden': true, className: 'size-4 shrink-0' }
                    )}
                  <Select.ItemText>{option.label}</Select.ItemText>
                  <Select.ItemIndicator className="absolute right-3 flex size-4 items-center justify-center">
                    <CheckIcon aria-hidden="true" className="size-4" />
                  </Select.ItemIndicator>
                </Select.Item>
              ))}
            </Select.Viewport>
          </Select.Content>
        </Select.Portal>
      </Select.Root>
    </div>
  );
});

Dependencies: radix-ui, 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.

Use display="icon-text" to show an icon beside the text. The default is display="text". For an icon-only action, use Icon Theme Toggle. Pass animationType, duration, and slideDirection to this control to set its UI theme transition. These props override the provider settings for this action only.

Keyboard focus shows the theme’s focus ring.

Edit the installed source. Use className in React or class in Vue to style the root. Use the classes prop to style individual parts. Use label props to change the visible text.