Skip to content
Nana UI

Forms & Inputs

Theme Toggle

Switches the page between light and dark themes, and can follow the system setting.

View .md Download

Theme Toggle is a Svelte component. It sets the page theme, remembers the choice, and marks the active option with the same liquid indicator as the segmented Tab Group. The new theme spreads across the page in a circle from the option that was pressed.

npx @nana-tec/ui add theme-toggle --framework svelte

Lands in src/lib/components/ui/theme-toggle/ as NanaThemeToggle.svelte, styled with Tailwind classes that resolve to the design tokens. Requires Tailwind v4.

<script lang="ts">
import { NanaThemeToggle } from '$lib/components/ui/theme-toggle';
</script>
<NanaThemeToggle />

The toggle sets data-theme and color-scheme on <html>, which every Nana theme reads, and stores the choice in localStorage under nana-theme. Pass storageKey to use a different key.

Add system to offer a third option that follows the operating system. Choosing it clears the stored choice, so the page tracks the system setting from then on, including when it changes while the page is open.

<NanaThemeToggle system />

Bind choice to read or set it from your app. A bound value takes precedence over the stored one, and setting it applies and stores the theme just as a click does. onThemeChange receives the theme now shown and the choice that produced it.

<script lang="ts">
import type { Theme, ThemeChoice } from '@nana-tec/ui-core/theme';
let choice = $state<ThemeChoice>('system');
function rememberChoice(_: Theme, next: ThemeChoice): void {
fetch('/api/preferences', { method: 'PATCH', body: JSON.stringify({ theme: next }) });
}
</script>
<NanaThemeToggle system bind:choice onThemeChange={rememberChoice} />

Several toggles on one page stay in step: a choice made in one is reflected in the others.

Set the theme before the first paint, or a dark page briefly shows light while the app loads. themeScript() returns a small inline script that reads the same storage key; place it in the document head.

src/routes/+layout.svelte
<script lang="ts">
import { themeScript } from '@nana-tec/ui-core/theme';
</script>
<svelte:head>
{@html `<script>${themeScript()}</script>`}
</svelte:head>

In SvelteKit you can paste the script’s output into src/app.html instead. If you pass a custom storageKey to the toggle, pass the same key to themeScript().

The page reveal uses the View Transitions API. In browsers without it, and for anyone who prefers reduced motion, the theme changes instantly and the indicator moves without animating. Set reveal={false} to keep the indicator animation but change the page instantly.

The toggle is a group labelled “Theme” (label changes it). Each option is a button with an accessible name and aria-pressed showing whether it is the current choice. Every option is reachable with Tab and activated with Enter or Space.

NanaThemeToggle

PropTypeDefault
sizeThemeToggleSize'md'
choicebind:ThemeChoiceundefined
systembooleanfalse
revealbooleantrue
storageKeystringTHEME_STORAGE_KEY
labelstring'Theme'
disabledbooleanfalse
onThemeChange(theme: Theme, choice: ThemeChoice) => void

Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class'>.