Toggle Button
An independent on/off control (e.g. Bold in a toolbar), built on a native
<button type="button"> that carries aria-pressed.
Import
Section titled “Import”<script> import ToggleButton from "@invisible-ui/svelte/ToggleButton.svelte";</script><script setup> import { ToggleButton } from "@invisible-ui/vue";</script>import { ToggleButton } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-toggle-button></ds-toggle-button>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>| Prop | Type | Default | Description |
|---|---|---|---|
pressed | boolean | false | Whether 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. |
disabled | boolean | false | |
check | boolean | false | Show 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. |
label | string | undefined | undefined | Accessible name; required when children is icon-only. |
name | string | undefined | undefined | Form field name — when checked, submits value under it. |
value | string | "on" | Value submitted under name when pressed. |
error | string | undefined | undefined | Error 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) | undefined | undefined | Called whenever pressed changes. |
| Prop | Type | Default | Description |
|---|---|---|---|
modelValue | boolean | undefined | Whether the button is pressed. v-model binds it two ways; passing it once and driving clicks through onPressedChange works as well. |
pressed | boolean | false | |
disabled | boolean | false | |
check | boolean | false | Show a leading checkmark when pressed (the filter-chip look). The check reveals the selected state explicitly, the way a checkbox does. |
label | string | undefined | Accessible name; required when the slot content is icon-only. |
name | string | undefined | Form field name; when pressed, submits value under it. |
value | string | "on" | Value submitted under name when pressed. |
error | string | undefined | Error message. When non-empty it shows after the control as an alert and describes the control. The application owns it: a form reset leaves it in place, and the application clears it. |
onPressedChange | (pressed: boolean) => void | undefined | Called whenever the pressed value changes. |
| Event | Payload |
|---|---|
update:modelValue | pressed: boolean |
Slots: default.
| Prop | Type | Default | Description |
|---|---|---|---|
pressed | boolean | false | Whether the button is pressed: the initial value, or the current one when it changes between renders (e.g. a filter chip driven by a list). |
disabled | boolean | false | |
error | string | — | An error message shown under the control as an alert. It describes the control. The app owns it: a form reset leaves it in place, so the app clears it. |
check | boolean | false | Show a leading checkmark when pressed (the filter-chip look). The check reveals the selected state explicitly, the way a checkbox does. |
label | string | — | Accessible name; required when the content is icon-only. |
name | string | — | Form field name; when pressed, submits value under it. |
value | string | "on" | Value submitted under name when pressed. |
onPressedChange | (pressed: boolean) => void | — | Called whenever the pressed value changes. |
children | ReactNode | — | The button's content. |
| Attribute | Reactive | Description |
|---|---|---|
pressed | yes | |
disabled | yes | |
check | yes | |
label | yes | |
name | yes | |
value | yes | |
error | yes | a message after the button; the page owns it, so a form reset leaves it in place |
Reactive attributes re-render the element when they change after the first render.
Properties: pressed, disabled.
Emits: bubbling change CustomEvent with detail.pressed.
Error message
Section titled “Error message”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.
Accessibility
Section titled “Accessibility”- 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. Exposesdata-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
labelwhen the slot content is icon-only so the control still has an accessible name. - Pass
name(and optionalvalue) to submit the pressed state with a form: while the button is pressed and enabled, a hidden input sendsvalueundername, 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
errorlinks the button to the message througharia-describedby. - Assistive technology: not tested.
Example
Section titled “Example”<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-*.