# Button Group

Related actions in one shape: Segmented, Attached or Toolbar. For a main action with a menu, use Split Button.

Tier: Free

## Installation

```bash
npx shadcn add @fetaui/button-group
```

## Usage

```tsx
import { ButtonGroup } from '@/components/fetaui/button-group'

const options = [
  { value: 'week', label: 'Week' },
  { value: 'month', label: 'Month' },
]

export function RangePicker() {
  return <ButtonGroup kind="segmented" label="Range" options={options} defaultValue="week" />
}
```

## API

| Prop | Type | Default |
|---|---|---|
| kind | segmented, attached, toolbar, or split (for a menu, use Split Button) | required |
| label | string | required |
| animated | boolean | true |
| Segmented options | { value, label, disabled? }[] | required |
| Segmented value | string |  |
| Segmented defaultValue | string | first option |
| Segmented onValueChange | (value) => void |  |
| Attached items | { label?, doneLabel?, icon?, ariaLabel?, onClick?, disabled? }[] | required |
| Toolbar items | { label, icon, pressed, onPressedChange, disabled? }[] or separator | required |

## When to use

- Segmented for one choice from a few short options.
- Attached for peer actions on the same object.
- Toolbar for formatting toggles.

## When not to use

- For a main action with a menu of related options: use Split Button.
- For unrelated actions: use separate Buttons.
- For many options: use a Select.

## Accessibility

- Segmented is a radio group, Toolbar a toolbar, Attached a labelled group.
- Icon only buttons need an accessible name.

## Motion

- The selected card slides on a spring.
- Text labels draw on hover and wave on press, like Button.
- Attached scales to 0.98 as one shape.
- An Attached item with doneLabel holds it for 1.6 s after a click, so Download reads Downloaded. The old word blurs out, the new one draws in, and the button eases to the new width.
- With reduced motion, the card jumps and labels stay still.