ColorSchemeButton handbook

v1.0.2 · @snowui-design-system/components

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

Switch between light and dark themes, with an icon showing the current scheme; suitable for a website or application theme control.

When to use it

Use to switch between light and dark schemes. New code uses this name; ThemeButton is a compatibility export. Use StyleButton to change visual style.

Sync light/dark state through bind:scheme or onSchemeChange; defaultScheme supplies the default scheme.
By default, sync the document theme. For local control, set applyToDocument={false}. Without children, use an icon-only layout.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { ColorSchemeButton } from '@snowui-design-system/components';</script> <ColorSchemeButton />

API

Keyword	Type	Default	Description
scheme	`ColorScheme`	—	Current color scheme; supports bind:scheme. Takes precedence over defaultScheme on mount. Clicks update this value, and it follows root attribute changes when document sync is enabled.
defaultScheme	`ColorScheme`	—	Uncontrolled initial value on mount; scheme takes precedence. If neither is provided, reads the page root; with applyToDocument=false, falls back to light.
applyToDocument	`boolean`	`true`	Syncs current state to document.documentElement: sets theme="dark" or removes theme for light. When false, the component does not read, write, or observe page attributes; the caller manages the theme target. Does not write storage.
ariaLabel	`string`	—	Overrides the accessible button name. The default describes the state a click will switch to and follows LocaleProvider.
lightIcon	`Snippet`	`— (built-in graphic)`	Replaces the Sun icon shown in the light state. Only the graphic changes; switch logic stays with the component.
darkIcon	`Snippet`	`— (built-in graphic)`	Replaces the Moon icon shown in the dark state. Only the graphic changes; switch logic stays with the component.
children	`Snippet`	—	Custom content shown after the state graphic. Without it, the host Button uses an iconOnly layout.
disabled	`boolean`	`false`	Disables button interaction but does not stop sync from an external bound value or page attribute.
onSchemeChange	`(scheme: ColorScheme) => void`	—	Receives the new value after a user click. Initialization, external assignments, and observed page-attribute changes do not call it.
onclick	`(event: MouseEvent) => void`	—	Called before the state switch on a valid click. The current implementation does not let preventDefault() cancel the subsequent switch. Not called when disabled.

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

Usage

<script lang="ts">  import { ColorSchemeButton } from "@snowui-design-system/components";</script> <ColorSchemeButton bare />

ColorSchemeButton forwards compatible Button Props and supports all variants and sizes. By default it reads document.documentElement: theme="dark" means dark, and no theme attribute means light. Without additional children it explicitly sets iconOnly=true on Button. Built-in Sun / Moon icons follow the Button size context: regular icon-only sm / md / lg sizes are 16 / 20 / 24px; bare icon-only uses Button sizes 12 / 16 / 20px.

The old name ThemeButton remains only as a deprecated compatibility alias; new code should use ColorSchemeButton.

A click updates the scheme immediately without writing storage. Icon replacement uses a 150ms transition; there is no whole-page theme transition. With applyToDocument={false}, the component maintains only controlled state, suitable when a host such as Test or an iframe manages the actual theme target.

This section is protected. An AI must request user review before modifying it.

ColorSchemeButton style overrides

Read the full LICENSE first; reuse that review for the same task, version, and scope.

First use public component Props to match the desired appearance, preserving the existing look where possible. If changes are necessary, follow the style selection and override order: use your own class (including Tailwind already in the project) or an instance style. The names below are public overrides actually consumed by source; check their scope and do not modify private DOM. Choose the correct SnowUI token family. External apps need not install SnowUI website utilities.

Variable	Purpose and default reference
`--snowui-color-scheme-button-motion-duration-override`	default: 150ms; Button hover / click

Design guide · Tokens · Composition boundaries

ColorSchemeButton types and state

Required Props: no named required Props.

Bindable Prop: bind:scheme.

Inheritance: Omit< ButtonProps, "children" | "onclick" | "disabled" | "aria-pressed" >. Consult the base class public documentation; fields excluded by Omit cannot be passed through unchanged.

Shared Frame API · Back to API

The following type declarations are actually referenced by public Props and come from source. A Svelte Snippet denotes a content fragment; ComponentProps denotes the Props of the corresponding component.

ColorScheme

Source: components/src/components/ColorSchemeButton.svelte

export type ColorScheme = "light" | "dark";

ButtonProps

Source: components/src/components/ColorSchemeButton.svelte

type ButtonProps = ComponentProps<typeof Button>;