ThemeToggle

Overview

The ThemeToggle component is a controlled light/dark/system mode switcher. It supports two visual variants — a single icon button that cycles on click, and a segmented pill group with one button per option. It's fully headless: you provide the current value and an onChange callback, so it works with any theme provider (next-themes, custom context, etc.).

Installation

Install the component via the CLI in one command.

npx @work-rjkashyap/unified-ui add theme-toggle

pnpm dlx @work-rjkashyap/unified-ui add theme-toggle

npx @work-rjkashyap/unified-ui add theme-toggle

bunx @work-rjkashyap/unified-ui add theme-toggle

Or install the full package

Use this approach if you prefer to install the entire design system as a dependency instead of copying individual components.

npm install @work-rjkashyap/unified-ui

pnpm add @work-rjkashyap/unified-ui

yarn add @work-rjkashyap/unified-ui

bun add @work-rjkashyap/unified-ui

Anatomy

import { ThemeToggle } from "@work-rjkashyap/unified-ui";

Examples

Icon Variant (Default)

import { useTheme } from "next-themes";import { ThemeToggle } from "@work-rjkashyap/unified-ui";function MyToggle() {const { resolvedTheme, setTheme } = useTheme();return (<ThemeTogglevalue={resolvedTheme as "light" | "dark"}onChange={setTheme}/>);}

Segmented Variant

<ThemeTogglevalue={theme}onChange={setTheme}variant="segmented"/>

Three-State Mode (Light / Dark / System)

// Icon variant — cycles: light → dark → system<ThemeTogglevalue={theme}onChange={setTheme}mode="light-dark-system"/>// Segmented variant — shows all three options<ThemeTogglevalue={theme}onChange={setTheme}variant="segmented"mode="light-dark-system"/>

Sizes

<ThemeToggle value={theme} onChange={setTheme} size="sm" /><ThemeToggle value={theme} onChange={setTheme} size="md" /><ThemeToggle value={theme} onChange={setTheme} size="lg" />

<ThemeToggle value={theme} onChange={setTheme} variant="segmented" size="sm" /><ThemeToggle value={theme} onChange={setTheme} variant="segmented" size="md" /><ThemeToggle value={theme} onChange={setTheme} variant="segmented" size="lg" />

Integration with next-themes

The most common integration is with next-themes:

"use client";

import { useTheme } from "next-themes";
import { ThemeToggle, type ThemeValue } from "@work-rjkashyap/unified-ui";
import { useEffect, useState } from "react";

export function SiteThemeToggle() {
	const { theme, setTheme, resolvedTheme } = useTheme();
	const [mounted, setMounted] = useState(false);

	useEffect(() => setMounted(true), []);

	if (!mounted) return null;

	// For 2-state mode, use resolvedTheme (never "system")
	// For 3-state mode, use theme (can be "system")
	return (
		<ThemeToggle
			value={(theme ?? "system") as ThemeValue}
			onChange={setTheme}
			mode="light-dark-system"
			variant="segmented"
		/>
	);
}

Props

ThemeToggle

Variants Reference

Accessibility

• Keyboard: The icon variant is a standard <button> — focusable and activatable with Enter or Space. The segmented variant uses role="radiogroup" with role="radio" on each option, supporting aria-checked.
• Focus ring: Uses the design system's standard focusRingClasses for visible keyboard focus.
• Labels: The icon variant sets a descriptive aria-label indicating which theme it will switch to. Each segmented button has an aria-label matching its theme name.
• Motion: Icon transitions use transition-all with duration-300 and respect prefers-reduced-motion via the standard Tailwind motion-safe / motion-reduce utilities.

Design Tokens