# Button group

## Overview

_[Design to fill]_

- **When to use**: _[Design to fill]_
- **When not to use**: _[Design to fill]_

## Anatomy

_[Design to fill]_

## Variants

The selection mode is derived from the type of `value`:

| `value` type | Mode            | Container role | Behavior                                          |
| ------------ | --------------- | -------------- | ------------------------------------------------- |
| `string`     | Single select   | `radiogroup`   | Selecting an option replaces the current value.   |
| `string[]`   | Multiple select | `group`        | Selecting an option toggles it in/out of the set. |

## Props / API

### `ButtonGroup`

| Prop         | Type                                | Default | Description                                                                 |
| ------------ | ----------------------------------- | ------- | --------------------------------------------------------------------------- |
| `value`      | `string \| string[] \| undefined`   | -       | Selected value(s). A `string[]` enables multiple-selection (checkbox) mode. |
| `onChange`   | `(value: ButtonGroupValue) => void` | -       | Called with the next value when the selection changes.                      |
| `isDisabled` | `boolean`                           | `false` | Disables all buttons in the group.                                          |
| `isSmall`    | `boolean`                           | `false` | Renders all buttons at the `small` size (otherwise `medium`).               |
| `children`   | `ReactNode`                         | -       | The `ButtonGroup.Button` elements that make up the group.                   |

Standard `<div>` attributes (except `onChange`) are forwarded via `...rest`.

### `ButtonGroup.Button`

| Prop         | Type        | Default | Description                              |
| ------------ | ----------- | ------- | ---------------------------------------- |
| `value`      | `string`    | -       | Identifies this option within the group. |
| `iconBefore` | `IconName`  | -       | Optional leading icon.                   |
| `children`   | `ReactNode` | -       | The option label.                        |

Must be rendered inside a `ButtonGroup`; using it outside throws.

## States

- Default (idle)
- Hover
- Active/pressed
- Focus-visible
- Selected — reflected via `aria-pressed="true"` and the `primary` button style.
- Disabled

## Code examples

```tsx
import { useState } from "react";
import { ButtonGroup, type ButtonGroupValue } from "@mylighthouse/prism-react";

export default function ButtonGroupExample(): React.JSX.Element {
  // Single select
  const [view, setView] = useState<ButtonGroupValue>("list");
  // Multiple select
  const [filters, setFilters] = useState<ButtonGroupValue>(["new"]);

  return (
    <>
      <ButtonGroup value={view} onChange={setView}>
        <ButtonGroup.Button iconBefore="list" value="list">
          List
        </ButtonGroup.Button>
        <ButtonGroup.Button iconBefore="grid" value="grid">
          Grid
        </ButtonGroup.Button>
      </ButtonGroup>

      <ButtonGroup value={filters} onChange={setFilters}>
        <ButtonGroup.Button value="new">New</ButtonGroup.Button>
        <ButtonGroup.Button value="open">Open</ButtonGroup.Button>
        <ButtonGroup.Button value="closed">Closed</ButtonGroup.Button>
      </ButtonGroup>
    </>
  );
}
```

## A11y intent

_[Design to fill]_

- The container carries the selection semantics: `radiogroup` for single select, `group` for multi-select.
- Each option exposes its selected state via `aria-pressed`, so state changes are announced, not conveyed by color alone (WCAG 1.4.1).
- `isDisabled` disables every button in the group while keeping them in the accessibility tree.
- Give the group an accessible name (e.g. `aria-label` on the group) so assistive tech announces its purpose.

## Cross-references

- **[Button](./button.md)**: a single action button; a button group arranges a fixed set of related, selectable options together.