# ButtonGroup

> Slug: `button-group` · Category: Actions

## When to use
- Group two or more related `Button`s as a coherent action set (e.g., "Save" + "Cancel").
- Control responsive arrangement (stacked on mobile, row on desktop) with one wrapper.
- Make all grouped buttons fill width on small viewports.

## When NOT to use
- A single button — render the `Button` directly.
- Buttons with surrounding helper copy or a "Need help?" link — use `ButtonTray` instead.
- Toggle or filter selections — use `Chips` or `StyledRadioGroup`.

## Variants & decision tree
- Vertical stack on all viewports -> `arrangement="column"`.
- Horizontal row -> `arrangement="row"` (or use the preset `ButtonGroupHorizontal`).
- Buttons should fill the row width -> `buttonSpan="fill"`. Hug content -> `buttonSpan="hug"` (default).
- Different layout per breakpoint -> use `smallButton*`, `mediumButton*`, `largeButton*` props (e.g., column+fill on small, row+hug on large).

## States
- Inherits inverse from `ArrowThemeProvider` or via `inverse` prop.
- Each child is wrapped in a `<li>` with optional `data-alignment` (`leading` | `center`).

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`children`** | `ReactNode` | — | One or more `Button`s. Each becomes a list item. |
| `arrangement` | `'column' \| 'row'` | — | Base arrangement. |
| `buttonSpan` | `'fill' \| 'hug'` | `'hug'` | Whether buttons fill or hug. |
| `smallButtonSpan` / `smallButtonArrangement` | same | — | Small-viewport overrides. |
| `mediumButtonSpan` / `mediumButtonArrangement` | same | — | Medium-viewport overrides. |
| `largeButtonSpan` / `largeButtonArrangement` | same | — | Large+ viewport overrides. |
| `alignment` | `'leading' \| 'center'` | — | Per-item alignment via `data-alignment`. |
| `inverse` | `boolean` | inherits | Dark-background styling. |

## Usage examples
```tsx
import { Button, ButtonGroup } from 'arrow-react-bootstrap';

// Stack on mobile, row on desktop
<ButtonGroup
  smallButtonSpan="fill"
  smallButtonArrangement="column"
  largeButtonSpan="hug"
  largeButtonArrangement="row"
>
  <Button variant="primary">Save</Button>
  <Button variant="secondary">Cancel</Button>
</ButtonGroup>

// Always horizontal, hug width
<ButtonGroup arrangement="row">
  <Button>Yes</Button>
  <Button variant="secondary">No</Button>
</ButtonGroup>
```

## Composition
- Wrap with `ButtonTray` when you also need a help link or supplementary text.
- Place as the trailing element in a `Modal`, `Tidbit`, or form footer.

## Accessibility
- Renders an `<ul role="list">` so SR users hear the action set as a list.
- Each child is a `<li role="listitem">`.
- The grouped `Button`s keep their own focusable behavior; group does not add roving tabindex.

## Do / Don't
- Do: pass `Button` (or `ButtonStyledAsLink` / `LinkStyledAsButton`) as children.
- Do: prefer responsive `*ButtonArrangement` overrides for adaptive layouts.
- Don't: wrap children in `<li>` yourself — the group adds list items automatically.
- Don't: mix unrelated controls (links + form fields) inside a single group.
