# Checkbox group

## Overview

_[Design to fill]_

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

## Anatomy

_[Design to fill]_

## Variants

| Prop      | Effect                                                           |
| --------- | ---------------------------------------------------------------- |
| `isSmall` | Renders the smaller size with `text-200` label sizing for items. |

## Props / API

### `CheckboxGroup`

| Prop        | Type                        | Default | Description                                                                      |
| ----------- | --------------------------- | ------- | -------------------------------------------------------------------------------- |
| `value`     | `string[]`                  | -       | The controlled list of checked item values.                                      |
| `onChange`  | `(value: string[]) => void` | -       | Called with the next list of checked values whenever selection changes.          |
| `allValues` | `string[]`                  | -       | The full set of selectable values, used to drive the parent checkbox.            |
| `isSmall`   | `boolean`                   | `false` | Renders the smaller size with `text-200` label sizing.                           |
| `disabled`  | `boolean`                   | `false` | Disables the whole group.                                                        |
| `className` | `string`                    | -       | Additional class names for the `<fieldset>`.                                     |
| `children`  | `React.ReactNode`           | -       | The group content, typically a `CheckboxGroup.Legend` and `CheckboxGroup.Item`s. |

Renders a `<fieldset>`.

### `CheckboxGroup.Legend`

Renders a `<legend>`. Extends `HTMLAttributes<HTMLLegendElement>`.

### `CheckboxGroup.Item`

| Prop       | Type      | Default | Description                                                             |
| ---------- | --------- | ------- | ----------------------------------------------------------------------- |
| `value`    | `string`  | -       | The value this item contributes to the group. Required for leaf items.  |
| `parent`   | `true`    | -       | Marks the item as the parent checkbox. Mutually exclusive with `value`. |
| `nested`   | `boolean` | `false` | Indents the item to show it is nested under a parent.                   |
| `disabled` | `boolean` | `false` | Disables this item.                                                     |
| `children` | -         | -       | The item label.                                                         |

Renders a `<label>`. A `parent` item omits `value`; a leaf item omits `parent`. Extends `HTMLAttributes<HTMLLabelElement>`.

## States

- Default (idle)
- Hover
- Focus-visible
- Checked
- Indeterminate (parent with a partial selection)
- Disabled

## Code examples

```tsx
import { useState } from "react";
import { CheckboxGroup } from "@mylighthouse/prism-react";

const ALL = ["email", "sms", "push"];

export default function CheckboxGroupExample(): React.JSX.Element {
  const [selected, setSelected] = useState<string[]>([]);

  return (
    <CheckboxGroup allValues={ALL} value={selected} onChange={setSelected}>
      <CheckboxGroup.Legend>Notifications</CheckboxGroup.Legend>
      <CheckboxGroup.Item parent>All channels</CheckboxGroup.Item>
      <CheckboxGroup.Item nested value="email">
        Email
      </CheckboxGroup.Item>
      <CheckboxGroup.Item nested value="sms">
        SMS
      </CheckboxGroup.Item>
      <CheckboxGroup.Item nested value="push">
        Push
      </CheckboxGroup.Item>
    </CheckboxGroup>
  );
}
```

## A11y intent

_[Design to fill]_

- The group is a real `<fieldset>` with a `<legend>`, so its purpose is announced when any item receives focus.
- Each item is a real native checkbox wrapped in a `<label>`, so checked/unchecked/indeterminate state, keyboard operation, and focus are handled correctly.
- The `parent` checkbox reflects a mixed (indeterminate) state when only some nested items are checked, and toggles all of them at once.
- A disabled group or item stays in the accessibility tree so its state is announced.

## Cross-references

- **[Checkbox](./checkbox.md)**: the single checkbox control used for standalone boolean input.