Forms & Inputs
Theme Toggle
Switches the page between light and dark themes, and can follow the system setting.
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.
<script lang="ts">
import { NanaThemeToggle } from '$lib/components/ui/theme-toggle';
</script>
<div class="flex flex-wrap items-center gap-6">
<NanaThemeToggle storageKey="starlight-theme" />
<NanaThemeToggle storageKey="starlight-theme" system size="sm" />
</div> Installation
Section titled “Installation”npx @nana-tec/ui add theme-toggle --framework svelteLands 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.
System option
Section titled “System option”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 />Controlling the choice
Section titled “Controlling the choice”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.
Avoiding a flash on load
Section titled “Avoiding a flash on load”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.
<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().
Motion
Section titled “Motion”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.
Accessibility
Section titled “Accessibility”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
| Prop | Type | Default |
|---|---|---|
size | ThemeToggleSize | 'md' |
choicebind: | ThemeChoice | undefined |
system | boolean | false |
reveal | boolean | true |
storageKey | string | THEME_STORAGE_KEY |
label | string | 'Theme' |
disabled | boolean | false |
onThemeChange | (theme: Theme, choice: ThemeChoice) => void |
Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class'>.