Theme Toggle

Switches the document between light and dark. Uncontrolled by default: it reads the class already on the element rather than flashing to its own idea of the default on mount.

src/components/ui/theme-toggle.tsx

About

From the component's own source, where it was written.

Switches the document between light and dark.

The class goes on document.documentElement, not on a wrapper. .dark defines the token values on the element it lands on and everything below inherits them, so a wrapper deeper in the tree cannot switch a subtree back — a descendant has no way to undo variables set above it.

Uncontrolled by default: it reads the class already on the element, so it agrees with whatever the page shipped with instead of flashing to its own idea of the default on mount. Pass dark/onDarkChange when the app owns the state.

The read happens in the initialiser, not in an effect. Reading in an effect loses the race against the effect that writes the class: that one ran first with the default false and cleared .dark before anything had looked at it, so merely rendering the component turned a dark page light.

Install

npx astralyx-ui add theme-toggle

Usage

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

<ThemeToggle />
<ThemeToggle dark={dark} onDarkChange={setDark} />

Composer

Change the props and the source below follows.

Props

size

variant

tsx

<ThemeToggle />

Examples

Toggle

tsx

<ThemeToggle />

Remembering the choice

tsx

// Two pieces. The app owns the state and writes it down; a script in
// <head> reads it back before the first paint, so the page never flashes
// the other theme while the bundle loads.
//
// index.html, in <head>, before the bundle
<script>
  try {
    var stored = localStorage.getItem('theme')
    document.documentElement.classList.toggle(
      'dark',
      stored ? stored === 'dark' : !matchMedia('(prefers-color-scheme: light)').matches,
    )
  } catch (e) {}
</script>

// The app: seed from the live element, persist every change.
const [dark, setDark] = useState(() =>
  document.documentElement.classList.contains('dark'),
)

useEffect(() => {
  document.documentElement.classList.toggle('dark', dark)
  try {
    localStorage.setItem('theme', dark ? 'dark' : 'light')
  } catch {}
}, [dark])

<ThemeToggle dark={dark} onDarkChange={setDark} />

API

Generated from the source, so it cannot fall behind the code. One table per exported component, then hooks, functions and types.

`ThemeToggle`

Switches the document between light and dark.

Extends Omit<ButtonProps, 'children' | 'onChange'>.

Prop	Type	Default	Description
color	'neutral' \| 'blue' \| 'violet' \| 'cyan' \| 'green' \| 'amber' \| 'rose' \| 'destructive'	—	—
variant	'link' \| 'default' \| 'colored' \| 'secondary' \| 'outline' \| 'ghost'	'secondary'	Passed through to Button.
size	'sm' \| 'default' \| 'xs' \| 'lg' \| 'xl' \| 'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg' \| 'icon-xl'	'icon-sm'	Passed through to Button.
asChild	boolean	—	Render the child element instead of a `<button>`, keeping the styles.
tint	string	—	Any CSS colour, used instead of a named `color` set. Fill, text, tint and border are all derived from it, and every variant keeps working.
dark	boolean	—	Controlled mode. Omit both and it manages itself.
onDarkChange	(dark: boolean) => void	—	Controlled mode. Omit both and it manages itself.
target	document.documentElement	—	The class goes on the root, never a wrapper: `.dark` defines the token values on the element it lands on, so a descendant cannot switch a subtree back.

Behaviour

Topic	Detail	Description
persistence	yours to add	The toggle does not remember the choice — it has no idea where your app keeps state. Store it, and re-apply the class from an inline script in <head> so the page does not paint the wrong palette first. Without both halves, every reload falls back to whatever the HTML shipped with.