# ButtonGroup

> Joins Buttons and IconButtons into one segmented row or column with shared outer corners.

Category: Actions. Docs page: https://rime.mjsons.net/components/button-group

## Installation

```bash
npx shadcn@latest add KezLahd/rime/button-group
```

ButtonGroup shapes related actions into one control: the outer corners keep the buttons' radius, the joins between them are square, and neighbouring edges share a single hairline. It only shapes; each button keeps its own variant, size, loading and disabled state.

Use it for a split button (a primary action plus a chevron for its options), a pair of previous and next buttons, or a short set of related secondary actions. For a choice that stays selected, use ToggleGroup or SegmentedControl instead.

## Usage

```tsx
import { Button, ButtonGroup } from "@/components/ui";

<ButtonGroup aria-label="Invoice actions">
  <Button variant="secondary">Archive</Button>
  <Button variant="secondary">Report</Button>
</ButtonGroup>
```

## Props: ButtonGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | horizontal (default) joins left to right; vertical stacks top to bottom. |

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes.

## Examples

### Groups and a split button

```tsx
<ButtonGroup aria-label="Invoice actions">
  <Button variant="secondary">Archive</Button>
  <Button variant="secondary">Report</Button>
  <Button variant="secondary">Snooze</Button>
</ButtonGroup>
<ButtonGroup aria-label="Send">
  <Button>Send invoice</Button>
  <IconButton variant="primary" label="More send options" icon={<IconChevronDown size={16} />} />
</ButtonGroup>
```

### Vertical

```tsx
<ButtonGroup orientation="vertical" aria-label="Order view">
  <Button variant="secondary">Details</Button>
  <Button variant="secondary">Line items</Button>
  <Button variant="secondary">History</Button>
</ButtonGroup>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--button-group-join` | `0` |

## Accessibility

- Renders role="group" with aria-orientation. Give it an aria-label that names the set ("Invoice actions").
- Every button stays a real, separately focusable button in reading order; hover and focus lift the button over its neighbours so its focus ring is drawn whole.

## Do

- Keep a group to one variant, except a split button's primary half.
- Group two to five actions that belong together.

## Don't

- Don't use a ButtonGroup for a selected state; that is ToggleGroup or SegmentedControl.
- Don't put two primary buttons in one group.

Related: https://rime.mjsons.net/components/button, https://rime.mjsons.net/components/toggle-group