# Radio

> Radio selects exactly one option from a set. RadioGroup shares a name across its options and exposes them as a single labelled group.

Source: https://vaneui.com/docs/form-components/radio

Import: `import { Radio, RadioGroup, Col, Field, Label, Row, Text } from "@vaneui/ui"`

Radio fits a short set of choices that should all stay visible. Each one is a native `<input type="radio">`, so the browser moves the selection with the arrow keys inside a group. RadioGroup takes `value`, `defaultValue` and `onChange` for the whole set and matches each option by its `value` prop. For a long list, use a [Select](/docs/form-components/select); when more than one option can be on, use [Checkbox](/docs/form-components/checkbox).

## Basic usage

Radio selects exactly one option from a set. Wrap the options in a `RadioGroup` so they share a name and behave as one control.

```tsx demo
<RadioGroup name="plan" defaultValue="pro">
  <Label row itemsCenter><Radio value="free"/> Free</Label>
  <Label row itemsCenter><Radio value="pro"/> Pro</Label>
  <Label row itemsCenter><Radio value="team"/> Team</Label>
</RadioGroup>
```

`RadioGroup` renders `role="radiogroup"` and generates a shared `name` when you do not pass one, so radios are mutually exclusive without extra wiring.

## With a group label

Inside a `Field`, the group is labelled by reference with `aria-labelledby`, because a radiogroup cannot be the target of `htmlFor`.

```tsx demo
<Field label="Billing period" description="Change it any time.">
  <RadioGroup name="billing" defaultValue="yearly">
    <Label row itemsCenter><Radio value="monthly"/> Monthly</Label>
    <Label row itemsCenter><Radio value="yearly"/> Yearly, two months free</Label>
  </RadioGroup>
</Field>
```

## Sizes

```tsx demo
<Col>
  <Label row itemsCenter xs><Radio name="s-xs" defaultChecked/> Extra small</Label>
  <Label row itemsCenter sm><Radio name="s-sm" defaultChecked/> Small</Label>
  <Label row itemsCenter md><Radio name="s-md" defaultChecked/> Medium</Label>
  <Label row itemsCenter lg><Radio name="s-lg" defaultChecked/> Large</Label>
  <Label row itemsCenter xl><Radio name="s-xl" defaultChecked/> Extra large</Label>
</Col>
```

## Appearances

Radio takes the same appearance props as Checkbox: the appearance colours the box border, the selected fill and the focus ring. Set it on the `Label` too when you want the text to match.

```tsx demo
<Row flexWrap>
  <Label row itemsCenter><Radio name="a-primary" defaultChecked/> primary (default)</Label>
  <Label row itemsCenter accent><Radio accent name="a-accent" defaultChecked/> accent</Label>
  <Label row itemsCenter secondary><Radio secondary name="a-secondary" defaultChecked/> secondary</Label>
  <Label row itemsCenter tertiary><Radio tertiary name="a-tertiary" defaultChecked/> tertiary</Label>
  <Label row itemsCenter success><Radio success name="a-success" defaultChecked/> success</Label>
  <Label row itemsCenter danger><Radio danger name="a-danger" defaultChecked/> danger</Label>
  <Label row itemsCenter warning><Radio warning name="a-warning" defaultChecked/> warning</Label>
  <Label row itemsCenter info><Radio info name="a-info" defaultChecked/> info</Label>
</Row>
```

## Shapes

Radio is `pill` by default, which is what distinguishes it from a Checkbox at a glance. `rounded` and `sharp` are available, but a square radio reads as a checkbox, so reach for them only when the surrounding design demands it.

```tsx demo
<Row flexWrap>
  <Label row itemsCenter><Radio name="sh-pill" defaultChecked/> pill, the default</Label>
  <Label row itemsCenter><Radio rounded name="sh-rounded" defaultChecked/> rounded</Label>
  <Label row itemsCenter><Radio sharp name="sh-sharp" defaultChecked/> sharp</Label>
</Row>
```

## Variants

Radio is `filled` by default: the box fills with the appearance colour when selected. `outline` keeps the box transparent and colours the dot instead.

```tsx demo
<Row flexWrap>
  <Label row itemsCenter><Radio name="v-filled" defaultChecked/> filled, the default</Label>
  <Label row itemsCenter><Radio outline name="v-outline" defaultChecked/> outline</Label>
  <Label row itemsCenter><Radio ghost name="v-ghost" defaultChecked/> ghost</Label>
</Row>
```

## Explicit size on the control

The Radio takes its own size prop, which wins over the size inherited from the Label.

```tsx demo
<Row flexWrap>
  <Label row itemsCenter lg><Radio xs name="sz-a" defaultChecked/> xs dot, lg label</Label>
  <Label row itemsCenter lg><Radio name="sz-b" defaultChecked/> inherited lg</Label>
  <Label row itemsCenter lg><Radio xl name="sz-c" defaultChecked/> xl dot, lg label</Label>
</Row>
```

## States

```tsx demo
<RadioGroup name="states" defaultValue="on">
  <Label row itemsCenter><Radio value="off"/> Unselected</Label>
  <Label row itemsCenter><Radio value="on"/> Selected</Label>
  <Label row itemsCenter><Radio value="no" disabled/> Disabled</Label>
</RadioGroup>
```

## Group state props

`RadioGroup` takes `disabled`, `readOnly`, `required` and `invalid`. Each one reaches every `Radio` in the group, and a `Radio`'s own prop wins. The group element also gets the matching `aria-disabled`, `aria-readonly`, `aria-required` and `aria-invalid` attributes. These props need `@vaneui/ui` 1.5.0 or later.

```tsx demo
<Row flexWrap itemsStart>
  <Col>
    <Text sm secondary>disabled</Text>
    <RadioGroup name="group-disabled" disabled defaultValue="free">
      <Label row itemsCenter><Radio value="free"/> Free</Label>
      <Label row itemsCenter><Radio value="pro"/> Pro</Label>
      <Label row itemsCenter><Radio value="team" disabled={false}/> Team, enabled</Label>
    </RadioGroup>
  </Col>
  <Col>
    <Text sm secondary>readOnly</Text>
    <RadioGroup name="group-readonly" readOnly defaultValue="pro">
      <Label row itemsCenter><Radio value="free"/> Free</Label>
      <Label row itemsCenter><Radio value="pro"/> Pro</Label>
    </RadioGroup>
  </Col>
  <Col>
    <Text sm secondary>invalid</Text>
    <RadioGroup name="group-invalid" invalid>
      <Label row itemsCenter><Radio value="free"/> Free</Label>
      <Label row itemsCenter><Radio value="pro"/> Pro</Label>
    </RadioGroup>
  </Col>
</Row>
```

Inside a [Field](/docs/form-components/field), the Field's own `disabled`, `readOnly`, `required` and `error` reach the group the same way.

## Props

| Prop | Category | Default | Description |
| --- | --- | --- | --- |
| `primary` | Appearance | yes | Primary color appearance (gray) |
| `accent` | Appearance |  | Accent color appearance (rose) |
| `secondary` | Appearance |  | Secondary color appearance (gray) |
| `tertiary` | Appearance |  | Tertiary color appearance |
| `success` | Appearance |  | Success color appearance (green) |
| `danger` | Appearance |  | Danger color appearance (red) |
| `warning` | Appearance |  | Warning color appearance (amber) |
| `info` | Appearance |  | Info color appearance (cyan) |
| `inheritAppearance` | Appearance |  | Inherit appearance from parent — suppresses own data-appearance/data-variant, uses parent's CSS variables |
| `disabled` | Disabled |  | Disable the component — reduces opacity, changes cursor to not-allowed, and prevents interaction |
| `readOnly` | Read Only |  | Render the field read-only — mutes it (lighter than disabled) and sets a default cursor; the value stays selectable and submittable |
| `pill` | Shape | yes | Fully rounded corners (circular) |
| `sharp` | Shape |  | No rounded corners (square) |
| `rounded` | Shape |  | Medium rounded corners (default) |
| `xs` | Size |  | Extra small size |
| `sm` | Size |  | Small size |
| `md` | Size | yes | Medium size (default) |
| `lg` | Size |  | Large size |
| `xl` | Size |  | Extra large size |
| `invalid` | Validity |  | Mark the field invalid (red border/ring), layered over any appearance |
| `filled` | Variant | yes | Filled variant - solid background with contrasting text color |
| `outline` | Variant |  | Outline variant - transparent background with border and colored text (default) |
| `ghost` | Variant |  | Ghost variant - transparent background, no border, appearance-colored text, tinted hover background |

Layout and utility props (Align Self, Border, Cursor, Display, Focus Visible, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).
