---
summary: 複数の選択肢から 1 つだけを選ばせるラジオボタン
category: Forms
---

# Radio

複数の選択肢から 1 つだけを選ばせるラジオボタンです。RadioGroup の中に Radio を並べて使います。
素の `<input type="radio">` の代わりに使います。
複数選択や単独の ON/OFF には Checkbox、選択肢が多く表示面積を抑えたい場合は Select を使ってください。

## 基本の使い方

```tsx
import { Radio, RadioGroup } from 'wip-ui'

<RadioGroup aria-label="権限" defaultValue="edit">
  <Radio value="admin">管理権限</Radio>
  <Radio value="edit">編集権限</Radio>
  <Radio value="view">閲覧権限</Radio>
</RadioGroup>
```

## 構成要素

| 部品 | 役割 |
|---|---|
| RadioGroup | Radio をまとめ、選択値を管理するコンテナ |
| Radio | 個々の選択肢 |

## 使う場面

- 2 つ以上の選択肢から 1 つだけを選ばせるとき
- 4 個以下の選択肢から選ばせるとき

## 使い方

### 構成

- [avoid] Radio を 1 つだけで使わない。単独の ON/OFF には Checkbox を使う
- RadioGroup には、グループの見える見出しを出す機能はない

### 選択値

- [should] 初期値として、どれか1つを選んでおく。既存の値がある場合はその値にする
- [should] 初期値にふさわしい選択肢がない場合は、「指定しない」などの選択肢を足して、それを初期値にする

### 無効

- [should] 特定の選択肢だけを選べなくする場合は、その Radio に isDisabled を指定する
- [should] すべての選択肢を操作できなくする場合は、RadioGroup に isDisabled を指定する

### 配置

- 選択肢は縦に並ぶ。横並びには対応していない

## 文言

- [should] ラベルは、モバイル幅でも1行に収まる短さにする
- [should] 選択肢どうしで、ラベルの長さをそろえる

## アクセシビリティ

- [must] RadioGroup に aria-label を付与し、グループの意味を伝える

## 実装

- [must] Radio は RadioGroup の中で使う
- [must] 各 Radio に、グループ内で一意の value を指定する
- [should] 初期値は defaultValue（制御する場合は value と onChange）で指定する

## Props（自動生成）

型定義から生成した props の一覧です。react-aria-components から引き継いだ props の説明は英語です。DOM の汎用的な属性・イベントは省略しています。

### Radio

| 名前 | 型 | 既定値 | 説明 |
|---|---|---|---|
| inputRef | RefObject<HTMLInputElement \| null> | - | A ref for the HTML input element. |
| value（必須） | string | - | The value of the radio button, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio#Value). |
| isDisabled | boolean | - | Whether the radio button is disabled or not. Shows that a selection exists, but is not available in that circumstance. |
| autoFocus | boolean | - | Whether the element should receive focus on render. |
| id | string | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| aria-label | string | - | Defines a string value that labels the current element. |
| aria-labelledby | string | - | Identifies the element (or elements) that labels the current element. |
| aria-describedby | string | - | Identifies the element (or elements) that describes the object. |
| aria-details | string | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| onPress | ((e: PressEvent) => void) | - | Handler that is called when the press is released over the target. |
| onPressStart | ((e: PressEvent) => void) | - | Handler that is called when a press interaction starts. |
| onPressEnd | ((e: PressEvent) => void) | - | Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target. |
| onPressChange | ((isPressed: boolean) => void) | - | Handler that is called when the press state changes. |
| onPressUp | ((e: PressEvent) => void) | - | Handler that is called when a press is released over the target, regardless of whether it started on the target or not. |
| onClick | ((e: MouseEvent<FocusableElement, MouseEvent>) => void) | - | **Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides  additional event details for non-mouse interactions. |
| children | ChildrenOrFunction<RadioRenderProps> | - | The children of the component. A function may be provided to alter the children based on component state. |
| className | ClassNameOrFunction<RadioRenderProps> | - | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| style | StyleOrFunction<RadioRenderProps> | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| slot | string \| null | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |

### RadioGroup

| 名前 | 型 | 既定値 | 説明 |
|---|---|---|---|
| value | string \| null | - | The current value (controlled). |
| isDisabled | boolean | - | Whether the input is disabled. |
| id | string | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| aria-label | string | - | Defines a string value that labels the current element. |
| aria-labelledby | string | - | Identifies the element (or elements) that labels the current element. |
| aria-describedby | string | - | Identifies the element (or elements) that describes the object. |
| aria-details | string | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| name | string | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| orientation | "horizontal" \| "vertical" | 'vertical' | The axis the Radio Button(s) should align with. |
| defaultValue | string \| null | - | The default value (uncontrolled). |
| onChange | ((value: string) => void) | - | Handler that is called when the value changes. |
| isReadOnly | boolean | - | Whether the input can be selected but not changed by the user. |
| isRequired | boolean | - | Whether user input is required on the input before form submission. |
| isInvalid | boolean | - | Whether the input value is invalid. |
| validate | ((value: string \| null) => true \| ValidationError \| null) | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| form | string | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| aria-errormessage | string | - | Identifies the element that provides an error message for the object. |
| validationBehavior | "native" \| "aria" | 'native' | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| children | ChildrenOrFunction<RadioRenderProps> | - | The children of the component. A function may be provided to alter the children based on component state. |
| className | ClassNameOrFunction<RadioRenderProps> | - | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| style | StyleOrFunction<RadioRenderProps> | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| slot | string \| null | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |