Forms

Toggle

Sliding switch implementing the WAI-ARIA switch pattern for a single on or off setting that applies immediately.

import { Toggle } from '@lostgradient/cinder/toggle';
formswitch
01

Overview

On/off switch input for binary settings, presented as a sliding pill control.

Usage

svelte 
<script lang="ts">
  import Toggle from '@lostgradient/cinder/toggle';
</script>

<Toggle id="email-notifications" label="Email notifications" />
Live preview
02

When to use

Use when
  • Flipping a single setting on or off with immediate effect such as notifications or dark mode.
Avoid when
  • Picking one option from a small fixed set — use segmented-control instead.
  • Collecting a deferred boolean (agreement, opt-in) in a Submit-style form — a switch implies immediate effect; use checkbox instead.
03

Examples

Basic toggle

Switch using the WAI-ARIA switch pattern (aria-checked reflects state).

Disabled toggle

A disabled switch is dimmed and non-interactive — clicks and keyboard activation are ignored while the visible label keeps it readable.

Multiple switches

Several independent on/off settings inside a fieldset. Each Toggle renders its own visible label, so no external <label for> wrapper is needed.

Icon-only / inline row

In a toolbar or table row where the meaning is already clear from context, hideLabel removes the visible text while keeping it as the accessible name.

04

Props

Props for toggle
Name Type Default Required Bindable Description
id text req Native id placed on the <button>; the rendered label uses aria-labelledby to name it (label id is derived as ${id}-label).
checked boolean false bind Whether the toggle is currently checked. Bindable — defaults to false.
onValueChangeRequest (next: boolean) => booleanvoid Intercept a proposed checked state before the bindable value is written. Return a replacement value to transform it.
onValueChange (next: boolean) => void Notify after the bindable value has been committed.
label text req Visible label text. Always the accessible name, even when hideLabel is set. Required.
disabled boolean Prevents interaction when true. Sets disabled attribute.
hideLabel boolean false Visually hide the rendered label while keeping it as the accessible name. Use for icon-only or inline contexts.
name text Form field name. When set, a hidden checkbox mirrors checked so the toggle participates in native form submission. Omit for purely client-side toggles (no hidden input is rendered, so there is zero overhead).
value text 'on' Value submitted for the hidden checkbox when checked and name is set. Mirrors native checkbox semantics: the pair name=value is sent only while checked. Defaults to 'on'. Ignored when name is unset.
form text Associates the hidden checkbox with a form by id, matching the native form attribute. Lets the toggle submit with a form it is not nested in. Ignored when name is unset.