# ButtonGroup

Related buttons, or an input and its buttons, joined into one control.

```ehtml Example
import { ButtonGroup, ButtonGroupSeparator, ButtonGroupText } from "@elements/ui/button-group";
import { Button } from "@elements/ui/button";

<ButtonGroup label="Message actions">
  <Button>Archive</Button>
  <Button>Report</Button>
  <Button>Snooze</Button>
</ButtonGroup>
```

## Parts

| Part | What it is |
|---|---|
| `ButtonGroupSeparator` | A rule between two members. |
| `ButtonGroupText` | A text or label segment. |
| `.button-group` | The base button-group classes, extended. Usable without the template. |

## Attributes

### ButtonGroup

| Attribute | Type | Default | Description |
|---|---|---|---|
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | A row or a column. |
| `label` | `string` | `""` | The group's accessible name (aria-label). |
| `class` | `string` | `""` | Extra classes. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | aria-labelledby, id, data-\*. |

### ButtonGroupSeparator

| Attribute | Type | Default | Description |
|---|---|---|---|
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | The rule's direction: vertical between buttons in a row. |

### ButtonGroupText

| Attribute | Type | Default | Description |
|---|---|---|---|
| `htmlFor` | `string` | `""` | Renders a `<label>` for that id instead of a `<div>`. |

## Slots

| Slot | Part | Content |
|---|---|---|
| `default` | `ButtonGroup` | Buttons, Inputs, NativeSelects, InputGroups, ButtonGroupText, separators, or nested ButtonGroups. |

## Keyboard

| Keys | Action |
|---|---|
| `Tab` | Moves through the members one by one (each is its own tab stop). |

## Data attributes

| Attribute | Values | On |
|---|---|---|
| `data-orientation` | `"horizontal" \| "vertical"` | group, separator |

## Accessibility

- role="group" with aria-orientation; name it with label or aria-labelledby.
- Every member stays its own tab stop. For one tab stop with arrow keys, use ToggleGroup.
- A hovered or focused member is raised so its border and focus ring are never hidden by a neighbour.

## See also

- [Button](button): A button or a link that looks like one, in six variants and four sizes.
- [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.
- [Label](label): A native label for a control, which dims when the control is disabled.