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

# Radio

数据录入`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

从一组互斥选项中选择一个值。

## 何时使用

选项数量较少且用户需要同时比较时使用 RadioGroup。

**推荐**

- 默认值应安全且合理。
- 选项标签描述结果而非动作。

**避免**

- 允许多选时不要使用 Radio，应使用 Checkbox。

## 代码演示


### 基础用法
```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;
```

### 独立状态
```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;
```

### 纵向选项组
```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;
```

### 受控单选组
Group 的 onChange 直接返回选项值。
```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>
  );
}
```

### 垂直与禁用选项
用纵向排列容纳较长选项，单个选项可禁用。
```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 },
      ]}
    />
  );
}
```

### 原生表单提交
设置组的 name 后，可从 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>
  );
}
```

### 单选组尺寸
同一组的选项继承尺寸，维持一致的对齐和点击区域。
```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



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| disabled | 是否禁用 | `boolean | undefined` | `-` |
| name | Native group name; generated when omitted to isolate keyboard navigation. | `string | undefined` | `-` |



### [#](#radio)Radio



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| disabled | 是否禁用 | `boolean | undefined` | `-` |

