Theme Toggle React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Theme Toggle is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import ThemeToggle from @/components/ui/theme-toggle.

"use client"

import { ThemeProvider } from "next-themes"
import { ThemeToggle } from "@/components/ui/theme-toggle"

// next-themes needs attribute="class" so the dark: variant and the reveal see the change
export function AppHeader() {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
      <header className="flex h-14 items-center justify-between px-4">
        <span className="font-semibold">Northwind CRM</span>
        <ThemeToggle
          shortcut="shift+t"
        />
      </header>
    </ThemeProvider>
  )
}

Props

• variantdefault "icon"
  "icon" | "segmented" | "dropdown"

  icon: an animated sun / moon button for headers. segmented: Light / Dark / System side by side for settings pages. dropdown: a button that opens a menu (a sheet on phones).

• includeSystemdefault true
  boolean

  Offers System, which follows the device. The icon button then cycles system -> the opposite of the device -> the device's theme -> system, so each press but the last visibly changes the page; without it the button flips light <-> dark, and a page on system shows as the theme it resolves to (no badge). Segmented and dropdown show a third option.

• sizedefault "md"
  "sm" | "md" | "lg"

  32 / 40 / 48px, like the button (md is 44px on touch). The glyph is 16 / 18 / 20px; the segmented track and the menu follow.

• radiusdefault "full"
  "none" | "sm" | "md" | "lg" | "full"

  Corner shape of the icon button, the dropdown trigger and the segmented track. Scales with the size.

• buttonVariantdefault "ghost"
  "solid" | "soft" | "outline" | "ghost" | "link"

  The look of the icon button and the dropdown trigger. ghost sits quietly in a header.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Color of the icon button and the dropdown trigger, and the fill of the segmented thumb (neutral is a raised white thumb).

• colordefault ""
  string

  Any CSS color; replaces the tone. Leave empty to use the tone.

• showLabelsdefault false
  boolean

  segmented: icons with labels (icons only by default, each with a tooltip). dropdown: the current theme's name and a chevron on the trigger.

• fullWidthdefault false
  boolean

  segmented: the segments share the full width of the parent, the usual layout for a settings row on a phone.

• transitiondefault "circle"
  "none" | "fade" | "circle"

  How the new theme appears: a circle growing from the control, a crossfade, or at once. Uses the View Transitions API (Chrome, Edge, Safari 18+), falls back to switching at once, and is off under reduced motion. The file also exports switchThemeWithTransition(apply, { transition?, duration?, origin? }), which runs any theme change inside the same reveal (origin is an element or a { x, y } point) and skips it while another one runs.

• durationdefault 500
  number

  Length of the reveal in ms.

• shortcutdefault ""
  string

  A key combo that flips light / dark from anywhere, e.g. "shift+t". Shown in the tooltip and set as aria-keyshortcuts. Empty binds nothing.

• disableddefault false
  boolean

  Dims the control and blocks it. It is also disabled on pages that force a theme (next-themes forcedTheme).

• defaultOpendefault false
  boolean

  dropdown: starts with the menu open.

• aligndefault "end"
  "start" | "center" | "end"

  dropdown: which edge of the menu lines up with the trigger. end suits a toggle at the end of a header.

• responsivedefault true
  boolean

  dropdown: the menu becomes a bottom sheet below 768px.

• value
  "light" | "dark" | "system"

  Controlled use without next-themes: the toggle shows this theme and only calls onValueChange. Left out, it reads and writes next-themes' useTheme(). For your own UI, useThemeToggle (see Parts) gives the same logic without the button.

• defaultValuedefault ""
  "light" | "dark" | "system"

  Uncontrolled use without next-themes: the starting theme. The toggle keeps its own state and reports picks through onValueChange. Left out (with value), it reads and writes next-themes; the playground's empty option means left out.

• onValueChange
  (theme: ThemeValue) => void

  Fires with every pick, inside the view transition, so the new theme you apply is what the reveal shows.

• open
  boolean

  dropdown: controls the menu.

• onOpenChange
  (open: boolean) => void

  dropdown: fires when the menu opens or closes.

• labels
  { light?, dark?, system?, toggle?, menu?, announceLight?, announceDark?, announceSystem? }

  Every string, merged over DEFAULT_THEME_TOGGLE_LABELS: "Light", "Dark", "System", "Toggle theme" (the icon button's name), "Theme" (group name, tooltip prefix, sheet title) and the screen reader announcements "Light theme", "Dark theme", "System theme".

• classNames
  Partial<Record<"icon" | "badge" | "label" | "chevron" | "item" | "thumb" | "content", string>>

  Extra classes for inner parts: the glyph, the system badge, the trigger label and chevron, segments or menu rows, the segmented thumb, the menu surface.

• className
  string

  Extra classes for the root: the button, the segmented track or the dropdown trigger.

Parts

FAQ

Used in

More React button components