> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# Radio

Data Entry`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Selects exactly one option from a mutually exclusive set.

## When to use

Use RadioGroup when every option is visible and only one can be selected.

**Recommended**

- Use concise labels.
- Provide a default value when one option is recommended or required.

**Avoid**

- Do not use RadioGroup for very long option lists; use Select instead.

## Examples


### Basic usage
```tsx preview
import { RadioGroup } from '@rockshin/tao-ui';
import { useState } from 'react';

function RadioExample() {
  const [value, setValue] = useState('pro');

  return (
    <RadioGroup
      value={value}
      onChange={setValue}
      options={[
        { label: 'Free', value: 'free' },
        { label: 'Pro', value: 'pro' },
        { label: 'Enterprise', value: 'enterprise', disabled: true },
      ]}
    />
  );
}

export default RadioExample;
```

### Standalone states
```tsx preview
import { Radio, RadioGroup, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';

function RadioStates() {
  const [value, setValue] = useState('selected');

  return (
    <RadioGroup value={value} onChange={setValue}>
      <Stack direction="horizontal" gap="lg">
        <Radio value="selected">Selected</Radio>
        <Radio value="idle">Unselected</Radio>
        <Radio value="disabled" disabled>
          Disabled
        </Radio>
      </Stack>
    </RadioGroup>
  );
}

export default RadioStates;
```

### Vertical group
```tsx preview
import { FormField, RadioGroup } from '@rockshin/tao-ui';
import { useState } from 'react';

function VerticalRadioGroup() {
  const [value, setValue] = useState('monthly');

  return (
    <FormField label="Billing frequency">
      <RadioGroup
        direction="vertical"
        value={value}
        onChange={setValue}
        options={[
          { label: 'Monthly', value: 'monthly' },
          { label: 'Yearly — save 20%', value: 'yearly' },
          { label: 'Enterprise contract', value: 'enterprise', disabled: true },
        ]}
      />
    </FormField>
  );
}

export default VerticalRadioGroup;
```

### Controlled radio group
Group onChange returns the selected value directly.
```tsx preview
import { useState } from 'react';
import { RadioGroup, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [value, setValue] = useState('Weekly');
  return (
    <Stack direction="vertical">
      <RadioGroup
        options={['Daily', 'Weekly', 'Monthly']}
        value={value}
        onChange={setValue}
      />
      <output>Frequency: {value}</output>
    </Stack>
  );
}
```

### Vertical and disabled options
Use a vertical layout for longer labels and disable individual options.
```tsx preview
import { RadioGroup } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <RadioGroup
      direction="vertical"
      defaultValue="standard"
      options={[
        { label: 'Standard delivery', value: 'standard' },
        { label: 'Express delivery', value: 'express' },
        { label: 'Same day (unavailable)', value: 'same-day', disabled: true },
      ]}
    />
  );
}
```

### Native form submission
Set a group name to read its selected value from FormData.
```tsx preview
import { useState } from 'react';
import { RadioGroup, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [result, setResult] = useState('');
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        setResult(String(new FormData(e.currentTarget).get('plan')));
      }}
    >
      <Stack direction="vertical">
        <RadioGroup name="plan" options={['Free', 'Pro']} defaultValue="Free" />
        <Button type="submit">Read plan</Button>
        <output>{result}</output>
      </Stack>
    </form>
  );
}
```

### Radio group sizes
Group options inherit size for consistent alignment and targets.
```tsx preview
import { RadioGroup, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical">
      {(['small', 'medium', 'large'] as const).map((size) => (
        <RadioGroup
          key={size}
          size={size}
          options={['A', 'B', 'C']}
          defaultValue="A"
        />
      ))}
    </Stack>
  );
}
```

## API


### [#](#radiogroup)RadioGroup



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| name | Native group name; generated when omitted to isolate keyboard navigation. | `string | undefined` | `-` |



### [#](#radio)Radio



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |

