Theme switch | Surflane

AvailableBase UI ToggleGroup composition

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Compare the same example at each size and density. Switching keeps input values and selection state. Size guidance and comparisons

One button steps light, dark and system. This frame follows it and keeps the choice after a reload; system follows the device as it changes.

variant='group' shows the three side by side, for a settings page. Where they don't fit, only the icons show. The button beside it drives the same frame, and onThemeChange reports the theme that applies, such as for theme-color.

Usage

Let people choose light, dark or the device's setting with one button that steps through them, naming the theme now and the next in its label and tooltip. The switch sets data-theme on the page's root element, or on target for a scoped region, with the theme crossfade, keeps the choice in data-theme-mode, and remembers it under persist. Switches on one target stay in step, since each reads the target back; onThemeChange tells your code the theme that applies. System resolves to light or dark by the device and follows it as it changes. variant='group' shows the three side by side, for a settings page, and only their icons where the names don't fit; in an AppShell sidebar, the switch is a row like the links, such as "Theme: System", its name a tooltip on the collapsed rail, and a group there shows the three only while the sidebar is expanded.

Don't offer only light and dark where the device's setting matters; system is the default.
Don't set data-theme elsewhere at the same time. Pass value and onValueChange to drive the switch from your own state, such as a cookie the server reads for the first paint.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

div → Tooltip → Button(icon, aria-label) | variant='group': div → SegmentedControl(aria-label) → light, dark, system (icon + name)

Keyboard and accessibility

The button names the theme now and the one a press sets, and shows the same in a tooltip. Enter or Space steps to the next.
variant='group' is a segmented control: Tab reaches it, arrow keys move between light, dark and system, and Enter or Space chooses. The chosen one is pressed; a name hidden for room stays for assistive technology.
The theme crossfades, and changes at once under reduced motion.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { ThemeSwitch, AppShell } from '@surflane/ui'

<ThemeSwitch />
<ThemeSwitch variant='group' />

// In a sidebar: a row like the links, an icon on the collapsed rail.
<AppShell.Footer>
  <ThemeSwitch />
</AppShell.Footer>

Key API

Theme switch — common wrapper props
Prop	Contract	Default
`value / defaultValue / onValueChange`	light \| dark \| system; the remembered choice, then the page's data-theme-mode, win over defaultValue	system
`variant`	cycle \| group	cycle
`onThemeChange`	(theme: light \| dark, mode) => void: hears the theme that applies on mount and whenever it changes, by this switch, another on the target, your own code or the device in system; such as for <meta name="theme-color">	—
`target`	a ref to the element the theme applies to, such as a preview	the page's root element
`persist`	the localStorage key that remembers an uncontrolled choice; false keeps it for the session. With value, your own state remembers it	'surflane-theme'
`labels`	label, light, dark, system, next(current, next)	English

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens

--surf-control-height--surf-radius-md