For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
Shadcn Labs/

Theme Transition

ThemeTransitionProvider and useThemeTransition: theme state animated by React's <ViewTransition>. Animate dark mode toggles with ready-made styles, installed with the shadcn CLI.

Installation

$ pnpm dlx shadcn@latest add @transition-kit/theme-transition

Setup

src/routes/__root.tsx
import {
  createRootRoute,
  HeadContent,
  Outlet,
  Scripts,
} from "@tanstack/react-router";
 
import {
  ThemeTransitionProvider,
  ThemeTransitionScript,
} from "@/components/transitions/theme-transition";
 
const RootDocument = () => (
  <html lang="en" suppressHydrationWarning>
    <head>
      <HeadContent />
      <ThemeTransitionScript />
    </head>
    <body>
      <ThemeTransitionProvider transition="circle-reveal">
        <Outlet />
      </ThemeTransitionProvider>
      <Scripts />
    </body>
  </html>
);
 
export const Route = createRootRoute({ component: RootDocument });

Usage

import { useThemeTransition } from "@/components/transitions/theme-transition";
 
export const ThemeButton = () => {
  const { resolvedTheme, setTheme, toggleTheme } = useThemeTransition();
 
  return (
    <>
      {/* The provider's style, starting at the pointer. */}
      <button type="button" onClick={(event) => toggleTheme({ origin: event })}>
        {resolvedTheme === "dark" ? "Light mode" : "Dark mode"}
      </button>
 
      {/* Another style for this change only. */}
      <button
        type="button"
        onClick={() => setTheme("system", { transition: "diagonal-wipe" })}
      >
        System
      </button>
    </>
  );
};

API Reference

ThemeTransitionProvider

PropTypeDefaultDescription
transitionstring"circle-reveal"Style slug used when setTheme and toggleTheme are called without one. Circle Reveal ships with the core.
defaultTheme"light" | "dark" | "system""system"Theme used before the stored one loads.
storageKeystring"theme"localStorage key. Synced across tabs; system follows prefers-color-scheme.
durationnumber-Milliseconds. Overrides every style's timing.
easingstring-Overrides every style's easing.
childrenReactNode-Must cover everything the user sees; its element is snapshotted.
...propsComponentProps<"div">-Spread onto the provider's element.

ThemeTransitionScript

PropTypeDefaultDescription
storageKeystring"theme"Must match the provider's.
defaultTheme"light" | "dark" | "system""system"Must match the provider's.
noncestring-Content-Security-Policy nonce.

useThemeTransition

PropertyTypeDescription
mountedbooleanfalse on the server and until the stored theme is read.
theme"light" | "dark" | "system"The selected theme.
resolvedTheme"light" | "dark"The active theme, with system resolved.
setTheme(theme: Theme, options?: ThemeTransitionOptions) => voidChanges the theme, animated.
toggleTheme(options?: ThemeTransitionOptions) => voidFlips between light and dark, animated.

ThemeTransitionOptions

OptionTypeDescription
transitionstringStyle slug for this change only. Defaults to the provider's transition.
origin{ clientX: number; clientY: number } | ElementThe viewport centre. Click event starts at the pointer; an element starts at its centre.

Styles