# RadioGroup

> A fieldset of Radio controls with one legend, hint and error.

URL: https://apogee.avaui.dev/docs/radio-group
Last updated: 2026-10-15

A fieldset of Radio controls with one legend, hint and error.

Last updated October 15, 2026

```astro
<RadioGroup legend="Plan" hint="You can change this later.">
<Radio name="plan" value="free" label="Free" checked />
<Radio name="plan" value="pro" label="Pro" />
<Radio name="plan" value="team" label="Team" />
</RadioGroup>
```

For options that need a description, an icon or a price, see [Choice card](https://apogee.avaui.dev/docs/choice-card).

## Add

```sh
npx @ava-ui/apogee add radio-group
```

Depends on `utils`. Use with `radio`.

## Usage

```astro
---
import RadioGroup from '@/components/apogee/RadioGroup/RadioGroup.astro'
import Radio from '@/components/apogee/Radio/Radio.astro'
---
<RadioGroup legend="Size" direction="row">
  <Radio name="plan" value="s" label="S" />
  <Radio name="plan" value="m" label="M" />
  <Radio name="plan" value="l" label="L" />
</RadioGroup>
```

## Anatomy

A `<fieldset>` with a `<legend>`, the controls in the default slot, and an optional hint or error paragraph the fieldset is described by.

## API

`@composable`. Any other native `<fieldset>` attribute (`disabled`, `form`) passes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `legend` | `string` | — | Group label (required). |
| `hint` | `string` | — | Helper text under the controls. |
| `error` | `string` | — | Error text; replaces the hint, sets `aria-invalid`. |
| `direction` | `'row' \| 'column'` | `'column'` | Lay the controls out in a row (wraps) or a column. |
| `id` | `string` | auto | Fieldset id; hint/error ids derive from it. |
| `class` | `string` | — | Extra classes on the fieldset, merged last. |

## Variants

```astro
<RadioGroup legend="Column">…</RadioGroup>
<RadioGroup legend="Row" direction="row">…</RadioGroup>
```

## States

```astro
<RadioGroup legend="With hint" hint="Helper text.">…</RadioGroup>
<RadioGroup legend="With error" error="Pick at least one.">…</RadioGroup>
<RadioGroup legend="Disabled" disabled>…</RadioGroup>
```

## Error tint

The group’s `error` tints every control inside it; the children need no `hasError` of their own.

```astro
<RadioGroup legend="Channels" error="Pick at least one">
<Radio label="Email" name="tint" value="a" />
<Radio label="SMS" name="tint" value="b" />
</RadioGroup>
```

## Examples

A plan picker with a hint under each option:

```astro
<RadioGroup legend="Plan">
<Radio name="plan" value="free" label="Free" hint="One project, community support." checked />
<Radio name="plan" value="pro" label="Pro · €12/mo" hint="Unlimited projects, email support." />
<Radio name="plan" value="team" label="Team · €30/mo" hint="Shared billing and roles." />
</RadioGroup>
```

## Accessibility

-   Native `<fieldset>`/`<legend>`: screen readers announce the legend with each control.
-   `role="radiogroup"` on the fieldset; arrow keys move between radios natively.
-   Hint and error are linked through `aria-describedby`; the error has `role="alert"`.
-   Pass `hasError` to the controls that are wrong so they draw the critical border too.

## Tokens

| Token | Used for |
| --- | --- |
| `--foreground-neutral` | Legend |
| `--foreground-neutral-faded` | Hint |
| `--foreground-critical` | Error |

## Do / Don’t

-   **Do** write the legend as the question or category (“Plan”, “Notify me about”).
-   **Do** use `direction="row"` for two or three short options only.
-   **Don’t** nest one group inside another.

## Content

-   Legend in sentence case, no trailing colon.
-   Error text says what to do (“Pick at least one”), not what went wrong.

## Related

[

RadioA single option in a mutually exclusive set — pair radios sharing the same name into a group.

](https://apogee.avaui.dev/docs/radio)[

CheckboxGroupA fieldset of Checkbox controls with one legend, hint and error.

](https://apogee.avaui.dev/docs/checkbox-group)[

SegmentedControlA row of connected, mutually exclusive options backed by native radios — pick one from a small, always-visible set.

](https://apogee.avaui.dev/docs/segmented-control)