Theme Switch

A flexible and accessible theme mode switcher component

Installation

npx scrollx-ui@latest add theme-switch

Usage

import { ThemeSwitch } from "@/components/ui/theme-switch";
import { Sun, Moon, Laptop } from "lucide-react";

<ThemeSwitch
  modes={["light", "dark", "system"]}
  icons={[
    <Sun key="sun-icon" size={16} />,
    <Moon key="moon-icon" size={16} />,
    <Laptop key="laptop-icon" size={16} />,
  ]}
  showInactiveIcons="all"
/>

Examples

API Reference

ThemeSwitch

A flexible and accessible theme mode switcher component for Next.js projects using next-themes. Supports multiple modes (e.g., light, dark, system), custom icons, and various display options.

Props

modes – An array of strings representing the available theme modes (e.g., ["light", "dark", "system"]). These should match the modes supported by next-themes. Default is ["light", "dark", "system"].

icons – An array of React nodes, each representing an icon for a corresponding mode. The order and length should match the modes array. Default is an empty array.

showActiveIconOnly – A boolean. If true, only the icon for the currently active mode is shown, centered in the switch. Default is false.

showInactiveIcons – Controls how inactive mode icons are displayed. Accepts "all" (show all), "none" (hide all), or "next" (show only the next mode's icon in the sequence). Default is "all".

className – A string of additional CSS classes to apply to the switch container.

...props – Any other valid HTML div attributes. These will be passed to the root container of the component.

Behavior

• Clicking the switch cycles to the next mode in the modes array.
• Icons are displayed according to showActiveIconOnly and showInactiveIcons props.
• Animated indicator highlights the current mode.
• Accessible: Uses button-like semantics and focus styles.

Changelog

2025-06-02 ThemeSwitch - icon-click Variant

This provides a more intuitive UX compared to the default sequential toggle.

Use this variant when you want users to set the theme directly instead of cycling through options.

Add the variant prop as shown below:

ThemeSwitch.tsx

<ThemeSwitch
  variant="icon-click"
  modes={["light", "dark", "system"]}
  icons={[
    <Sun key="sun-icon" size={16} />,
    <Moon key="moon-icon" size={16} />,
    <Laptop key="laptop-icon" size={16} />,
  ]}
  showInactiveIcons="all"
/>