All components (204)

Toggle button

Actions · ToggleButton · .amset-togglebutton

What it is and when to use it

A button that stays pressed: the bold of an editor, "show the grid", "mute". It is a native <button aria-pressed>, so the keyboard, the focus and what the screen reader announces are the browser's.

When to use it

An option that switches on and off without leaving the screen: an editor format, a map layer, the view mode.
Inside a Toolbar, with hiddenLabel and an icon: the bar takes care of the arrow keys and the single Tab stop.
shortcut to announce the shortcut that does the same (Control+B).

When not to

Choosing ONE option among several that exclude each other: SegmentedGroup.
A filter with its own color: ToggleChip.
A setting that gets saved (turning notifications on): Switch.
An action done once: Button or IconButton.

Keyboard: Tab reaches the button; Enter and Space toggle it.

Accessibility: label is required and is the button's own text: with hiddenLabel it is not visible but it is still read, so what the screen reader says and what a voice control user says match (WCAG 2.5.3). Pressed is not just a color: the background fills and a bar appears under the content, which is what remains in high contrast.

Fine-tuning: CSS variables --amset-togglebutton-selected-background, -selected-ink and -mark (the thickness of the bar), on top of the button's.

What it looks like

List view · no bold

<ToggleButton label="Grid" icon={<LayoutGridIcon />} selected={cuadricula} onChange={setCuadricula} variant="outline" />
<ToggleButton label="Bold" hiddenLabel selected={negrita} onChange={setNegrita} shortcut="Control+B" variant="ghost" />

Props

Import it with import { ToggleButton } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`label`required	`string`	The button's name, always. With `hiddenLabel` it is not visible but it is still read: it is the button's own text, so what the screen reader says and what a voice control user says match (WCAG 2.5.3).
`className`	`string`	Merged with the library classes; it does not replace them.
`defaultSelected`	`boolean`	Pressed at the start, managing its own state.
`disabled`	`boolean`	Out of play: it can be neither pressed nor focused.
`hiddenLabel`	`boolean`	Hides the name and leaves only the icon, in a square button.
`icon`	`ReactNode`	Icon before the name. Decorative: the name comes from `label`.
`onChange`	`(selected: boolean) => void`	Called with the NEW value: `true` when pressed, `false` when released.
`selected`	`boolean`	Pressed or not, controlled from outside.
`shortcut`	`string`	The keyboard shortcut that does the same, in the `aria-keyshortcuts` format (`Control+B`). The screen reader announces it; whoever owns the shortcut listens to it, not the button.
`size`	`"sm" \| "md" \| "lg"`	Height of 30, 36 or 44 px, like the buttons. With touch, nothing goes below 44 px.
`variant`	`ToggleButtonVariant`	—

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

CSS variables

These CSS variables are how you adapt it. Declare them on the component's selector, not on :root: the stylesheet redeclares them in the rule itself, and a declaration on the same element always wins.

Variable	Default
`--amset-togglebutton-selected-background`	`var(--amset-accent-soft)`
`--amset-togglebutton-selected-ink`	`var(--amset-accent-text)`
`--amset-togglebutton-mark`	`calc(var(--amset-border-width) * 2)`

How to change it

.amset-togglebutton {
  --amset-togglebutton-selected-background: ...;
  --amset-togglebutton-selected-ink: ...;
}

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: