# ChoiceGroup

> Pick one or many from a short set, each choice with a title and a line of detail.

- **Level**: molecule · **Status**: stable · **Role**: input
- **Import**: `import { ChoiceGroup, ChoiceGroupItem } from "@rrios-forge/ui/molecules/choice-group";`
- **Source**: `packages/ui/src/molecules/choice-group`

Pick one or many from a set, each with a title and a line of detail. A fieldset with its legend, an optional description and an optional error, holding checkboxes, radios or switches; vertical or horizontal, comfortable or compact. For radios, wrap the items in a RadioGroup so arrow keys move between them.

## Use it for

- Binary toggle / checkbox / radio group → `Switch` (in `SettingsField` with label) / `Checkbox` / `ChoiceGroup` with `Radio`

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `orientation` | — | `vertical` `horizontal` | `vertical` | The direction the parts run: a row (horizontal) or a column (vertical); responsive stacks on phones and runs in a row from sm. |
| `invalid` | — | `true` `false` | `false` | Fails validation: a danger edge, announced as invalid; pair it with an error message. |

## Stories

- [Playground](/?path=/story/components-molecules-choicegroup--playground) · frame: `/iframe.html?id=components-molecules-choicegroup--playground&viewMode=story`
- [Checkbox choices](/?path=/story/components-molecules-choicegroup--checkbox-choices) · frame: `/iframe.html?id=components-molecules-choicegroup--checkbox-choices&viewMode=story`
- [Radio choices](/?path=/story/components-molecules-choicegroup--radio-choices) · frame: `/iframe.html?id=components-molecules-choicegroup--radio-choices&viewMode=story`
- [Switch choices](/?path=/story/components-molecules-choicegroup--switch-choices) · frame: `/iframe.html?id=components-molecules-choicegroup--switch-choices&viewMode=story`
- [Invalid](/?path=/story/components-molecules-choicegroup--invalid) · frame: `/iframe.html?id=components-molecules-choicegroup--invalid&viewMode=story`
- [Horizontal](/?path=/story/components-molecules-choicegroup--horizontal) · frame: `/iframe.html?id=components-molecules-choicegroup--horizontal&viewMode=story`

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).