Theme Toggle

Animated light/dark pill switch with sun and moon icons.

Installation

npx shadcn@latest add @iconiq/theme-toggle

Props

ThemeToggle

Client-only pill switch that toggles light and dark mode by adding or removing the `dark` class on `document.documentElement`, with sun and moon icons inside a sliding knob.

size"sm" | "md" | "lg"

Default md

Controls track, knob, and icon dimensions. Use `sm` in compact toolbars and `lg` for hero or settings layouts.

classNamestring

Optional class names merged onto the root button for spacing or layout in your header or settings panel.

On mount, the control reads `prefers-color-scheme: dark` and syncs both local state and the document `dark` class.

Before hydration completes, a neutral placeholder button is rendered to avoid layout shift while keeping an accessible name.

The toggle manages theme locally via the `dark` class; pair it with your own CSS variables or Tailwind dark mode setup.

Install path is `components/ui/theme-toggle.tsx` with the `ThemeToggle` export.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: @base-ui/react/toggle, lucide-react.

This page documents the Base UI install only. Theme Toggle uses the Base UI Toggle primitive for pressed state.

The generated registry file is /r/theme-toggle.json.