Skip to content

Toggle Button

An independent on/off control (e.g. Bold in a toolbar), built on a native <button type="button"> that carries aria-pressed.

<script>
import ToggleButton from "@invisible-ui/svelte/ToggleButton.svelte";
</script>

In Elements, the children are the visible content. The pressed state is reflected by the pressed attribute and reported through the bubbling change event with detail.pressed:

<ds-toggle-button label="Bold" name="bold">B</ds-toggle-button>
PropTypeDefaultDescription
pressedbooleanfalseWhether the button is pressed. Controlled: changing it updates the control, so it can reflect external selection state. For uncontrolled use, pass it once and drive clicks via onPressedChange.
disabledbooleanfalse
checkbooleanfalseShow a leading checkmark when pressed (the filter-chip look) — reveals the selected state explicitly, the way a checkbox does. Pairs with ToggleGroup for multi-select filter chips.
labelstring | undefinedundefinedAccessible name; required when children is icon-only.
namestring | undefinedundefinedForm field name — when checked, submits value under it.
valuestring"on"Value submitted under name when pressed.
errorstring | undefinedundefinedError message, shown after the button and announced. The button points at it through aria-describedby. The app owns it: a form reset leaves it in place, so the app clears it.
onPressedChange((p: boolean) => void) | undefinedundefinedCalled whenever pressed changes.

A non-empty error shows the message under the control with a hazard icon and announces it as an alert. The button points at it through aria-describedby. The button takes no aria-invalid. The message is plain text.

<ToggleButton check bind:pressed error={pressed ? "" : "Turn on email updates to get the code."}>
Email updates
</ToggleButton>

The app owns the message and clears it: a form reset leaves it in place. In Flutter, the validator’s message clears on form reset.

  • A native button with aria-pressed, following the WAI-ARIA button pattern: the browser owns the role and focus, and Enter and Space toggle it. Exposes data-state="on" \| "off" for styling.
  • The accessible name never changes with the state: only the pressed state does. Keep the label the same (“Bold”), not “Bold on” and “Bold off”.
  • Provide label when the slot content is icon-only so the control still has an accessible name.
  • Pass name (and optional value) to submit the pressed state with a form: while the button is pressed and enabled, a hidden input sends value under name, as a checked checkbox would. This form participation is provisional and may change.
  • Distinct from Switch: a toggle button is an action, a switch is a setting.
  • A non-empty error links the button to the message through aria-describedby.
  • Assistive technology: not tested.
<ToggleButton label="Bold" onPressedChange={(on) => setBold(on)}>B</ToggleButton>

In React, the content is children, and onPressedChange reports each press:

<ToggleButton label="Bold" pressed={bold} onPressedChange={setBold}>
<BoldIcon />
</ToggleButton>

Themeable via --ds-toggle-*.