Switch

A composable boolean switch with controlled and uncontrolled checked state, hidden input form support, and a headless thumb part for custom styling.

Enable notifications

Anatomy

The switch is assembled from two parts. Switch.Root renders the track (and a hidden checkbox input for form integration); Switch.Thumb renders the moving indicator.

<script>
	import { Switch } from '@human-kit/ui';
</script>

<Switch.Root aria-label="Enable notifications">
	<Switch.Thumb />
</Switch.Root>

States

Every visual state is exposed through data-* attributes on both parts, so all styling — including disabled and readonly — is done with plain CSS or utility classes.

Forms

Switch.Root keeps a hidden checkbox in sync: give it a name and value and the pair is submitted when the switch is on. value only affects form submission, never the visual state.

Usage guidelines

Use checked / defaultChecked for the switch state.
Use onCheckedChange to react to user-driven state changes.
Use value only for form submission through the hidden native input; it does not represent the visual state.
Wrap the switch in a native <label> for the simplest accessible labeling pattern, or point a sibling label[for] at the switch id.

Accessibility

Switch.Root exposes role="switch" with aria-checked="true" | "false".
Press Space to toggle the switch.
readonly keeps the switch focusable while preventing state changes.

API reference

Root

The switch control. Renders a span with role="switch" and keeps a hidden checkbox input in sync for form integration.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Data attribute Description

data-checked Present while the switch is on.

data-disabled Present when the switch is disabled.

data-focus-visible Present while focus should be visibly indicated (keyboard modality).

data-focused Present while the switch has focus.

data-pressed Present while the switch is actively pressed via pointer or keyboard.

data-readonly Present when the switch is readonly.

data-required Present when the switch is required.

data-switch-input Identifies the hidden native input.

data-switch-root Identifies the root element.

data-unchecked Present while the switch is off.

Thumb

The moving indicator. Mirrors the root state through data attributes for styling.