# RadioGroup

```tsx
import { RadioGroup } from '@tangible/ui';
```

Interactive docs and examples: [RadioGroup in Storybook](https://storybook-tangible-ui.pages.dev/?path=/docs/forms-radiogroup--docs).

## RadioGroup props

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `ReactNode` | | |
| `aria-describedby?` | `string` | | |
| `aria-invalid?` | `"false" \| "true" \| boolean` | | |
| `aria-label?` | `string` | | |
| `aria-labelledby?` | `string` | | |
| `aria-required?` | `"false" \| "true" \| boolean` | | |
| `className?` | `string` | | |
| `defaultValue?` | `OptionValue` | | |
| `disabled?` | `boolean` | `false` | |
| `loop?` | `boolean` | `true` | |
| `onValueChange?` | `(value: OptionValue) => void` | | |
| `orientation?` | `"horizontal" \| "vertical"` | `'vertical'` | |
| `value?` | `OptionValue` | | |

### RadioGroup.Item

Also exported as `Radio`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `value` | `OptionValue` | | |
| `aria-label?` | `string` | | |
| `aria-labelledby?` | `string` | | |
| `children?` | `ReactNode` | | |
| `className?` | `string` | | |
| `description?` | `string` | | Description text displayed below the label. |
| `disabled?` | `boolean` | `false` | |
| `label?` | `ReactNode` | | |

Also accepts the standard attributes of `HTMLAttributes` (`data-*`, `aria-*`, event handlers), passed to the element it renders.

## Examples

- [With Field](https://storybook-tangible-ui.pages.dev/?path=/story/forms-radiogroup--with-field): RadioGroup inside a Field — `Field.Label` provides the group name via
  `aria-labelledby` (injected by `Field.Control`). Helper text linked
  via `aria-describedby`. Note `as="span"`: a radiogroup is a `<div>`,
  not a labelable element, so a `<label for>` would be invalid HTML —
  the span carries the same id and the aria wiring is unchanged.

- [With Field Error](https://storybook-tangible-ui.pages.dev/?path=/story/forms-radiogroup--with-field-error): Error state — `Field.Control` injects `aria-invalid` and `aria-describedby`
  (pointing to the error). `Field.Label` provides the group name.

- [With Descriptions](https://storybook-tangible-ui.pages.dev/?path=/story/forms-radiogroup--with-descriptions): Each radio option can include a `description` prop for supplementary text
  displayed below the label. The description is linked to the radio button
  via `aria-describedby`.

- [With Nested Controls](https://storybook-tangible-ui.pages.dev/?path=/story/forms-radiogroup--with-nested-controls): Radio options accept `children` for nested interactive content — e.g. a
  number input that appears when a particular option is selected.

  Arrow keys on the nested input are **not** intercepted by the radio group,
  so `<input type="number">` spinners work as expected.

- [Custom Size](https://storybook-tangible-ui.pages.dev/?path=/story/forms-radiogroup--custom-size): Component API tokens control sizing and spacing. Here `--tui-radio-size`
  scales the indicator and `--tui-radio-group-gap` controls item spacing.
  The body indent adjusts automatically from `--tui-radio-size`.

Other stories: Basic, Horizontal, No Default Selection, Disabled, Disabled Option, Controlled, Dot Notation ([interactive page](https://storybook-tangible-ui.pages.dev/?path=/docs/forms-radiogroup--docs)).

## Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.

- `--tui-radio-accent`
- `--tui-radio-size`
- `--tui-radio-border`
- `--tui-radio-border-hover`
- `--tui-radio-border-invalid`
- `--tui-radio-bg`
- `--tui-radio-gap`
- `--tui-radio-font-size`
- `--tui-radio-label-color`
- `--tui-radio-description-color`
- `--tui-radio-group-gap`

---

Interactive version: https://storybook-tangible-ui.pages.dev/?path=/docs/forms-radiogroup--docs