Forms

ThemeSwitch

Three-position Light, System, Dark switch on a quiet sky and night track, for choosing a color theme.

import { ThemeSwitch } from '@lostgradient/cinder';
formswitchthemeappearance
01

Overview

Reference usage

A three-position Light, System, Dark switch in the Toggle family. A quiet pale sky sits behind Light, a deep night behind Dark, and the neutral inset surface behind System, with a raised thumb under the selected icon.

Use it to let a person choose a color theme in a header, a user menu, or a settings page. It reports the choice through value and onValueChange and does not change the document: applying the theme, and remembering it, is the application's job. Choose Toggle for a single on or off setting, and SegmentedControl for a longer list of labeled choices.

Usage

svelte 
<script lang="ts">
  import { ThemeSwitch, type ThemeSwitchValue } from '@lostgradient/cinder';

  let theme = $state<ThemeSwitchValue>('system');
</script>

<ThemeSwitch bind:value={theme} label="Color theme" />

System is the default position. Pass onValueChange to react to a selection, for example to set data-theme on the root element:

svelte 
<script lang="ts">
  import { ThemeSwitch, type ThemeSwitchValue } from '@lostgradient/cinder';

  function apply(next: ThemeSwitchValue): void {
    document.documentElement.dataset['theme'] = next;
  }
</script>

<ThemeSwitch value="system" onValueChange={apply} />

Behavior

The switch is a radiogroup of three buttons with role="radio", so exactly one position is always selected. Clicking a position selects it. With keyboard focus on the group, the arrow keys move to the next or previous position (wrapping at the ends) and select it as they go, and Home and End select Light and Dark. Selecting the position that is already selected reports nothing.

Live preview

Basic theme switch

Selected: system

02

When to use

Use when
  • Letting a person choose between a light theme, a dark theme, and following their system setting.
  • Placing the theme choice in a header, a user menu, or a settings page as one compact control.
Avoid when
  • Flipping a single setting on or off — use toggle instead.
  • Picking one option from a longer list of labeled choices — use segmented-control instead.
03

Examples

Basic theme switch

Three positions on a sky and night track: Light, System, Dark. Click a position or use the arrow keys, Home and End; the switch reports the selected value.

Disabled theme switch

A disabled switch keeps its selection and ignores the pointer and the keyboard.

04

Props

Props for theme-switch
Name
Type
Default
Description
id text Native id placed on the radiogroup element.
value bindable 'light' | 'system' | 'dark' 'system' The selected position. Bindable.
onValueChange (next: ThemeSwitchValue) => void Notify after the user selects a position, with the position that was selected.
label text 'Theme' Accessible name of the radiogroup. The three positions are named Light, System and Dark.
disabled boolean false Prevents interaction when true. Sets disabled on each position.