Theme Toggle

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

Installation

npx shadcn@latest add @iconiq/theme-toggle

File Structure

Usage

"use client";

import { ThemeToggle } from "@/components/ui/theme-toggle";

export function ThemeTogglePreview() {
  return (
    <div className="flex min-h-[18rem] items-center justify-center px-4 py-6">
      <p className="flex flex-wrap items-center justify-center gap-x-2 gap-y-1.5 text-balance text-[13px] text-muted-foreground leading-snug tracking-tight sm:text-sm">
        <span>Switch between light</span>
        <span className="inline-flex translate-y-px items-center align-middle">
          <ThemeToggle />
        </span>
        <span>and dark.</span>
      </p>
    </div>
  );
}

Props

Props
Description

ThemeToggle

size

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

Type "sm" | "md" | "lg"·Default md

pressed

Controlled dark-mode state. Pair with `onPressedChange` when wiring the toggle to next-themes or another theme provider.

Type boolean

defaultPressed

Initial dark-mode state for uncontrolled usage when no saved preference or system preference is available.

Type boolean

onPressedChange

Called when the user toggles theme. Receives `true` for dark mode and `false` for light mode.

Type (pressed: boolean) => void

persist

When enabled, writes `light` or `dark` to `localStorage` using `storageKey`. Disable when an external theme layer owns persistence.

Type boolean·Default true

storageKey

localStorage key used for saved theme preference. Defaults to `theme` for next-themes compatibility.

Type string·Default "theme"

enableSystem

When no saved preference exists, resolve the initial theme from `prefers-color-scheme` and keep following system changes until the user toggles manually.

Type boolean·Default true

applyToDocument

When enabled, toggles the `dark` class and `color-scheme` style on `document.documentElement`. Disable for controlled integrations that already apply theme changes.

Type boolean·Default true

disabled

Prevents interaction and dims the control.

Type boolean

aria-label

Accessible name for the toggle button.

Type string·Default "Toggle theme"

id

Forwarded to the underlying toggle button.

Type string

className

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

Type string

trackClassName

Optional class names merged onto the outer track button.

Type string

knobClassName

Optional class names merged onto the sliding knob.

Type string

ref

Ref forwarded to the rendered button element.

Type Ref<HTMLButtonElement>

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.

Contact

Additionally, if you find any bug or issue, feel free to raise an issue.

Switch between lightand dark.