elements
Manual UI Templates ToggleGroup

ToggleGroup

elements man ui/templates/toggle-group

A set of toggle buttons, one or many on, with one tab stop and arrow keys.

Example
import { ToggleGroup, ToggleGroupItem } from "@elements/ui/toggle-group";
import { Icon } from "@elements/ui/icon";

<ToggleGroup type="multiple" values={editor.marks} label="Text formatting">
  <ToggleGroupItem value="bold" label="Bold"><Icon name="bold" /></ToggleGroupItem>
  <ToggleGroupItem value="italic" label="Italic"><Icon name="italic" /></ToggleGroupItem>
</ToggleGroup>

<ToggleGroup type="single" value={view.filter} variant="outline" spacing={0}>
  <ToggleGroupItem value="all">All</ToggleGroupItem>
  <ToggleGroupItem value="missed">Missed</ToggleGroupItem>
</ToggleGroup>

Parts

Part What it is
.toggle-group The role="group" container; its data attributes style the items.
.toggle-group-item A .toggle button with data-value.

Attributes

ToggleGroup

Attribute Type Default Description
type "single" | "multiple" "single" One item on at most, or any number.
value string (two-way) "" single: the pressed item's value, or empty.
values string[] (two-way) [] multiple: the pressed items' values.
variant "default" | "outline" "default" Item look.
size "sm" | "md" | "lg" "md" Item height.
spacing 0 | 1 | 2 | 3 | 4 2 Gap from the space scale; 0 joins the items into one segmented control.
orientation "horizontal" | "vertical" "horizontal" Row or column, and which arrows move.
disabled boolean false Disables every item.
rovingFocus boolean true One tab stop with arrow keys. Off, every item is a tab stop.
loop boolean true Arrows wrap at the ends.
dir "ltr" | "rtl" | "" "" Reading direction; empty follows the page.
label string "" The group's accessible name.
class / attrs string / Record "" / {} Extra classes and attributes on the group.
onValueChange (value: string, details: ChangeDetails) => void () => {} single: the user pressed an item. It runs before the change with details second (reason, event, cancel(), isCanceled); details.cancel() keeps the value.
onValuesChange (values: string[], details: ChangeDetails) => void () => {} multiple: the user pressed an item. It runs before the change with details second (reason, event, cancel(), isCanceled); details.cancel() keeps the values.

ToggleGroupItem

Attribute Type Default Description
value string (required) This item's value.
label string "" Accessible name; required for icon-only items.
disabled boolean false This item cannot be pressed; arrows skip it.
class / attrs string / Record "" / {} Extra classes and attributes on the button.

Slots

Slot Part Content
default ToggleGroup ToggleGroupItem parts.
default ToggleGroupItem An icon, text, or both.

Keyboard

Keys Action
Tab Into the group on the pressed item, or the first.
Space / Enter Presses the focused item.
ArrowRight / ArrowDown Next item (ArrowLeft in right to left; vertical uses Up and Down).
ArrowLeft / ArrowUp Previous item.
Home / End First or last item.

Data attributes

Attribute Values On Description
data-orientation "horizontal" | "vertical" group, item
data-variant / data-size / data-spacing / data-type the attribute group
data-multiple present when type is multiple group
data-state "on" | "off" item
data-pressed present while pressed item The same state as data-state="on", as a presence attribute.
data-disabled present while disabled group, item

Accessibility

  • role="group" named by label. Items are buttons: aria-pressed in multiple mode, role="radio" with aria-checked in single mode.
  • One tab stop (roving tabindex) on the pressed item, or the first; arrows move without pressing; disabled items are skipped.
  • Icon-only items need label.

See also