# ToggleGroup

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

```ehtml 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

- [Icon](icon): An inline stroke icon from the set the templates draw their own controls with, sized in pixels and colored by the text around it.
- [ButtonGroup](button-group): Related buttons, or an input and its buttons, joined into one control.
- [Input](input): A native text input in the theme's control chrome, with a two-way value.
- [InputGroup](input-group): An Input or Textarea with icons, text and buttons inside one box.
- [Textarea](textarea): A native multi-line input that grows with its content, between rows and maxRows.
- [Field](field): A label, a control, a description and an error wired together, with native validation that never moves the layout.