# Theme Toggle
The sun eclipses into a moon, and the new theme spreads from the button as a circle.
**Category:** Display
**Exports:** `ThemeToggle`
**npm dependencies:** motion (+ clsx, tailwind-merge for `cn`)
## Install
```bash
npx shadcn@latest add https://charcoalui.com/r/theme-toggle.json
```
The file lands at `components/ui/theme-toggle.tsx`; import from `@/components/ui/theme-toggle`.
## API — Theme Toggle
| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `theme` | `"light" \| "dark"` | — | Omit to let the toggle manage the class. |
| `onThemeChange` | `(theme) => void` | — | |
| `reveal` | `boolean` | `true` | Circular reveal via View Transitions. |
| `storageKey` | `string` | `"charcoal-theme"` | |
## Example — Theme Toggle
```tsx
import { ThemeToggle } from "@/components/ui/theme-toggle";
export default function ThemeToggleDemo({ reveal = true, hint = "Click to switch the whole site." }: { reveal?: boolean; hint?: string }) {
return (
);
}
```
## Source — components/ui/theme-toggle.tsx
```tsx
"use client";
import * as React from "react";
import { motion, useReducedMotion } from "motion/react";
import { cn } from "@/lib/utils";
export type Theme = "light" | "dark";
export type ThemeToggleProps = Omit, "onClick"> & {
theme?: Theme;
onThemeChange?: (theme: Theme) => void;
/** localStorage key used when the toggle manages the theme itself. */
storageKey?: string;
/** Reveal the new theme with a circle growing out of the button (View Transitions API). */
reveal?: boolean;
};
function readTheme(): Theme {
if (typeof document === "undefined") return "dark";
return document.documentElement.classList.contains("dark") ? "dark" : "light";
}
export function ThemeToggle({
theme: themeProp,
onThemeChange,
storageKey = "charcoal-theme",
reveal = true,
className,
...props
}: ThemeToggleProps) {
const reduce = useReducedMotion();
const maskId = `moon${React.useId().replace(/[^a-zA-Z0-9]/g, "")}`;
const ref = React.useRef(null);
const [inner, setInner] = React.useState("dark");
React.useEffect(() => setInner(readTheme()), []);
const theme = themeProp ?? inner;
const dark = theme === "dark";
const apply = (next: Theme) => {
if (themeProp === undefined) {
document.documentElement.classList.toggle("dark", next === "dark");
try {
localStorage.setItem(storageKey, next);
} catch {}
setInner(next);
}
onThemeChange?.(next);
};
const toggle = () => {
const next: Theme = dark ? "light" : "dark";
const doc = document as Document & { startViewTransition?: (cb: () => void) => { ready: Promise } };
if (!reveal || reduce || !doc.startViewTransition || !ref.current) return apply(next);
const r = ref.current.getBoundingClientRect();
const x = r.left + r.width / 2;
const y = r.top + r.height / 2;
const radius = Math.hypot(Math.max(x, innerWidth - x), Math.max(y, innerHeight - y));
const transition = doc.startViewTransition(() => apply(next));
transition.ready.then(() => {
document.documentElement.animate(
{ clipPath: [`circle(0px at ${x}px ${y}px)`, `circle(${radius}px at ${x}px ${y}px)`] },
{ duration: 520, easing: "cubic-bezier(0.22, 1, 0.36, 1)", pseudoElement: "::view-transition-new(root)" },
);
});
};
const spring = reduce ? { duration: 0 } : { type: "spring" as const, stiffness: 300, damping: 22 };
return (
);
}
```