# ButtonGroup

> Groups related buttons, either joined into a segmented bar or evenly spaced.

Category: Actions · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/button-group

Use ButtonGroup to show that several actions belong together, such as export formats or pagination steps. Attached groups read as one control; spaced groups simply align actions like dialog footers. For buttons that hold an on/off state, use ToggleButtonGroup instead.

## Import

```tsx
import { ButtonGroup } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Attached

```tsx
import { Button, ButtonGroup } from '@bindshq/stance-react';

export function Attached() {
  return (
    <ButtonGroup label="Export as">
      <Button variant="outline">PDF</Button>
      <Button variant="outline">HTML</Button>
      <Button variant="outline">Plain text</Button>
    </ButtonGroup>
  );
}
```

### Spaced

```tsx
import { Button, ButtonGroup } from '@bindshq/stance-react';

export function Spaced() {
  return (
    <ButtonGroup variant="spaced" label="Template actions">
      <Button variant="ghost">Cancel</Button>
      <Button variant="outline">Save draft</Button>
      <Button>Publish</Button>
    </ButtonGroup>
  );
}
```

### Vertical

```tsx
import { Button, ButtonGroup } from '@bindshq/stance-react';

export function Vertical() {
  return (
    <ButtonGroup orientation="vertical" label="Deploy to">
      <Button variant="outline">Microsoft 365</Button>
      <Button variant="outline">Google Workspace</Button>
      <Button variant="outline">Exchange relay</Button>
    </ButtonGroup>
  );
}
```

### With icon buttons

```tsx
import { Button, ButtonGroup, Icon, IconButton } from '@bindshq/stance-react';

export function WithIconButtons() {
  return (
    <ButtonGroup label="Zoom">
      <IconButton variant="outline" label="Zoom out" icon={<Icon name="minus" />} />
      <Button variant="outline">100%</Button>
      <IconButton variant="outline" label="Zoom in" icon={<Icon name="plus" />} />
    </ButtonGroup>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| ButtonGroup | `variant` | `'attached' \| 'spaced'` | `'attached'` | Join buttons or keep a gap between them. |
| ButtonGroup | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction. |
| ButtonGroup | `label` | `string` | None | Accessible name for the group. |
| ButtonGroup | `fullWidth` | `boolean` | `false` | Buttons share the full container width. |

## Accessibility

- Renders role="group"; provide label so screen readers announce what the buttons relate to.
- Each button remains its own tab stop. For a single tab stop with arrow keys, use Toolbar or ToggleButtonGroup.

## Keyboard

| Keys | Action |
| --- | --- |
| `Tab` | Moves between the buttons in the group. |

## Guidelines

**Do**

- Keep attached groups to between two and five actions of equal importance.

**Don’t**

- Mix primary and outline buttons in one attached group.

## Related

- https://stanceui.com/components/button
- https://stanceui.com/components/toggle-button
- https://stanceui.com/components/split-button
- https://stanceui.com/components/toolbar