# Theme Toggle

> Source: https://design.nanatec.co.ke/components/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](/components/tab-group/). The new theme spreads across the page in a circle from
the option that was pressed.

## Installation

```bash
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.

## Usage

```svelte
<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

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.

```svelte
<NanaThemeToggle system />
```

## 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.

```svelte
<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

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.

```svelte
<!-- 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()`.

## 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

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.

## API
