React Theme Switcher Button

Powered by

React

Framer Motion

Lucide React

Tailwind CSS

Theme switchers are everywhere—navigation bars, settings panels, mobile apps. But most are just basic toggles between light and dark. Binary. Limited. No system detection. Meanwhile, users expect intelligent theme management that respects their OS preferences and provides smooth visual transitions. This React component gives you a complete theme switcher button with light, dark, and system modes, animated icon transitions, and persistent storage that creates a seamless theming experience.

'use client';import { ThemeSwitcher } from '@/components/ui/shadcn-io/theme-switcher';import { useState } from 'react';const Example = () => {  const [theme, setTheme] = useState<'light' | 'dark' | 'system'>('system');  return (    <ThemeSwitcher defaultValue="system" onChange={setTheme} value={theme} />  );};export default Example;

'use client';import { useControllableState } from '@radix-ui/react-use-controllable-state';import { Monitor, Moon, Sun } from 'lucide-react';import { motion } from 'motion/react';import { useCallback, useEffect, useState } from 'react';import { cn } from '@/lib/utils';const themes = [  {    key: 'system',    icon: Monitor,    label: 'System theme',  },  {    key: 'light',    icon: Sun,    label: 'Light theme',  },  {    key: 'dark',    icon: Moon,    label: 'Dark theme',  },];export type ThemeSwitcherProps = {  value?: 'light' | 'dark' | 'system';  onChange?: (theme: 'light' | 'dark' | 'system') => void;  defaultValue?: 'light' | 'dark' | 'system';  className?: string;};export const ThemeSwitcher = ({  value,  onChange,  defaultValue = 'system',  className,}: ThemeSwitcherProps) => {  const [theme, setTheme] = useControllableState({    defaultProp: defaultValue,    prop: value,    onChange,  });  const [mounted, setMounted] = useState(false);  const handleThemeClick = useCallback(    (themeKey: 'light' | 'dark' | 'system') => {      setTheme(themeKey);    },    [setTheme]  );  // Prevent hydration mismatch  useEffect(() => {    setMounted(true);  }, []);  if (!mounted) {    return null;  }  return (    <div      className={cn(        'relative isolate flex h-8 rounded-full bg-background p-1 ring-1 ring-border',        className      )}    >      {themes.map(({ key, icon: Icon, label }) => {        const isActive = theme === key;        return (          <button            aria-label={label}            className="relative h-6 w-6 rounded-full"            key={key}            onClick={() => handleThemeClick(key as 'light' | 'dark' | 'system')}            type="button"          >            {isActive && (              <motion.div                className="absolute inset-0 rounded-full bg-secondary"                layoutId="activeTheme"                transition={{ type: 'spring', duration: 0.5 }}              />            )}            <Icon              className={cn(                'relative z-10 m-auto h-4 w-4',                isActive ? 'text-foreground' : 'text-muted-foreground'              )}            />          </button>        );      })}    </div>  );};

Built for React applications with TypeScript and Next.js. Uses Framer Motion for smooth icon animations and Lucide icons for crisp sun/moon rendering. The component doesn't just toggle themes—it detects system preferences, persists user choices, and provides visual feedback during transitions. Perfect for shadcn/ui design systems with consistent styling patterns and accessibility support.

Why most theme toggles feel incomplete

Developers add a light/dark toggle and think they're done with theming. Maybe they store the preference in localStorage if they're being thorough. The problem? Users have system-wide theme preferences that get ignored. There's no visual feedback during theme changes. Icon transitions feel jarring and disconnected. It's functional but not thoughtful.

This component provides three-way theme selection: light, dark, and system auto-detection. Smooth icon animations create visual continuity during theme changes. System preference detection respects user choices at the OS level. The controlled/uncontrolled pattern gives you full flexibility over state management while handling all the complex theme coordination automatically.

Built with proper ARIA attributes and keyboard navigation, so theme switching works seamlessly for all users regardless of how they interact with your interface.

Installation

npx shadcn@latest add https://www.shadcn.io/registry/theme-switcher.json

npx shadcn@latest add https://www.shadcn.io/registry/theme-switcher.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/theme-switcher.json

bunx shadcn@latest add https://www.shadcn.io/registry/theme-switcher.json

Examples

Size Options

Three sizes for different interface densities:

'use client';import { ThemeSwitcher } from '@/components/ui/shadcn-io/theme-switcher';import { useState } from 'react';const Example = () => {  const [theme1, setTheme1] = useState<'light' | 'dark' | 'system'>('system');  const [theme2, setTheme2] = useState<'light' | 'dark' | 'system'>('system');  const [theme3, setTheme3] = useState<'light' | 'dark' | 'system'>('system');  return (    <div className="flex items-center justify-center gap-8 p-8">      {/* Small */}      <div className="flex flex-col items-center gap-3">        <ThemeSwitcher           value={theme1}           onChange={setTheme1}          className="scale-75"        />        <div className="text-center">          <span className="text-xs font-medium">Small</span>          <p className="text-xs text-muted-foreground">75% scale</p>        </div>      </div>      {/* Default */}      <div className="flex flex-col items-center gap-3">        <ThemeSwitcher           value={theme2}           onChange={setTheme2}        />        <div className="text-center">          <span className="text-xs font-medium">Default</span>          <p className="text-xs text-muted-foreground">100% scale</p>        </div>      </div>      {/* Large */}      <div className="flex flex-col items-center gap-3">        <ThemeSwitcher           value={theme3}           onChange={setTheme3}          className="scale-125"        />        <div className="text-center">          <span className="text-xs font-medium">Large</span>          <p className="text-xs text-muted-foreground">125% scale</p>        </div>      </div>    </div>  );};export default Example;

'use client';import { useControllableState } from '@radix-ui/react-use-controllable-state';import { Monitor, Moon, Sun } from 'lucide-react';import { motion } from 'motion/react';import { useCallback, useEffect, useState } from 'react';import { cn } from '@/lib/utils';const themes = [  {    key: 'system',    icon: Monitor,    label: 'System theme',  },  {    key: 'light',    icon: Sun,    label: 'Light theme',  },  {    key: 'dark',    icon: Moon,    label: 'Dark theme',  },];export type ThemeSwitcherProps = {  value?: 'light' | 'dark' | 'system';  onChange?: (theme: 'light' | 'dark' | 'system') => void;  defaultValue?: 'light' | 'dark' | 'system';  className?: string;};export const ThemeSwitcher = ({  value,  onChange,  defaultValue = 'system',  className,}: ThemeSwitcherProps) => {  const [theme, setTheme] = useControllableState({    defaultProp: defaultValue,    prop: value,    onChange,  });  const [mounted, setMounted] = useState(false);  const handleThemeClick = useCallback(    (themeKey: 'light' | 'dark' | 'system') => {      setTheme(themeKey);    },    [setTheme]  );  // Prevent hydration mismatch  useEffect(() => {    setMounted(true);  }, []);  if (!mounted) {    return null;  }  return (    <div      className={cn(        'relative isolate flex h-8 rounded-full bg-background p-1 ring-1 ring-border',        className      )}    >      {themes.map(({ key, icon: Icon, label }) => {        const isActive = theme === key;        return (          <button            aria-label={label}            className="relative h-6 w-6 rounded-full"            key={key}            onClick={() => handleThemeClick(key as 'light' | 'dark' | 'system')}            type="button"          >            {isActive && (              <motion.div                className="absolute inset-0 rounded-full bg-secondary"                layoutId="activeTheme"                transition={{ type: 'spring', duration: 0.5 }}              />            )}            <Icon              className={cn(                'relative z-10 m-auto h-4 w-4',                isActive ? 'text-foreground' : 'text-muted-foreground'              )}            />          </button>        );      })}    </div>  );};

Features

• Triple theme modes with light, dark, and system preference detection using JavaScript media queries
• System preference sync automatically following OS theme changes with real-time updates
• Smooth icon animations with sun/moon transitions using Framer Motion physics
• Persistent storage saving theme preferences to localStorage with automatic restoration
• Controlled/uncontrolled modes supporting both external state management and internal handling
• TypeScript definitions with complete interface definitions and theme type safety
• Accessibility features with keyboard navigation and proper ARIA labels
• Lucide icon integration for crisp, scalable sun and moon icons at any size
• Custom styling support with className props and Tailwind CSS compatibility
• Next.js optimization with SSR-safe theme detection and hydration handling

Use Cases

This free open source React component works perfectly for:

• Application headers - Global theme control in navigation bars and toolbars built with Next.js
• Settings panels - User preference configuration in app settings pages using TypeScript
• Dashboard controls - Quick theme switching in admin and data interfaces
• Content platforms - Reader-friendly dark mode toggles for articles and documentation
• Mobile applications - Native-feeling theme controls with system preference respect
• Design systems - Consistent theme switching across component libraries
• Developer tools - Code editor and IDE theme controls with professional feel
• E-commerce sites - User preference theming for shopping and browsing experiences

API Reference

ThemeSwitcher

The main component for three-way theme switching with system detection.

Theme States

System Detection

The component automatically detects and responds to:

• Initial system preference on component mount
• Real-time system changes via prefers-color-scheme media queries
• Storage persistence preserving user selections across sessions
• SSR compatibility with Next.js hydration and server-side rendering

Animation Specifications

Common gotchas

System theme detection timing: The component detects system preferences on mount, but initial render might show default state. This is normal for SSR compatibility and prevents hydration mismatches.

Storage persistence conflicts: If you're using multiple theme management libraries, ensure they don't conflict with localStorage keys. The component uses a specific key pattern that should be unique to your application.

Icon animation performance: Rapid theme switching can queue multiple animations. The component handles this gracefully, but very fast clicking might create visual overlap on slower devices.

CSS variable propagation: Theme changes update CSS custom properties at the document level. Ensure your theme CSS variables are properly scoped to avoid conflicts with other styling systems.

Controlled state synchronization: When using controlled mode, ensure your state updates are synchronous with the onChange callback to prevent animation glitches during theme transitions.

System preference overrides: When set to 'system' mode, manual theme changes will temporarily override system detection until the component is reset or remounted.

You might also like

Explore other interactive button components for React applications:

Questions developers actually ask