Toggle

A headless two-state button with controlled and uncontrolled selected state, native button semantics, and modality-aware styling hooks.

Anatomy

Toggle.Root is the only part: a native <button type="button"> with aria-pressed. Its children can optionally be a snippet that receives the current render state.

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

<Toggle.Root defaultSelected aria-label="Favorite">Favorite</Toggle.Root>

Standalone buttons

Every visual state is exposed through data-* attributes — data-selected, data-pressed, data-hovered, data-focus-visible, data-disabled — so all styling is done with plain CSS or utility classes. Use defaultSelected for uncontrolled state.

Controlled state

Bind selected to drive the toggle externally, and use onChange to react to user-driven changes.

Usage guidelines

• Use selected / defaultSelected for the toggle state.
• In controlled or bound usage, selected={undefined} syncs as false; omit selected to use defaultSelected.
• Use onChange to react to user-driven state changes.
• Use value as a stable identifier for composition with ToggleGroup; it is forwarded to the button and does not represent the selected state.
• Icon-only toggles must provide an accessible name through aria-label or aria-labelledby.
• If the visible label changes with state, keep the accessible name stable and let aria-pressed announce the state.

Accessibility

• Toggle.Root renders a native <button type="button">.
• The selected state is exposed to assistive technology with aria-pressed="true" | "false".
• Native keyboard activation is supported with Enter and Space.
• data-focus-visible follows the shared modality contract and is only exposed for keyboard or virtual focus.

API reference

Root

The toggle button. Renders a native <button type="button"> with aria-pressed and exposes selected and interaction state through data attributes.

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