---
summary: 定義済みの選択肢から 1 つを選ばせるドロップダウン
category: Forms
---

# Select

ドロップダウンで、定義済みの選択肢から 1 つを選ばせるフォームコンポーネントです。選択肢は SelectItem で渡します。
素の `<select>` の代わりに使います。
選択肢が 4 個以下の場合は RadioGroup + Radio、自由入力が必要な場合は TextField、複数選択には Checkbox、表示の切り替えには Tabs を使ってください。

## 基本の使い方

```tsx
import { Select, SelectItem } from 'wip-ui'

<Select label="都道府県" name="prefecture" placeholder="選択してください">
  <SelectItem id="hokkaido">北海道</SelectItem>
  <SelectItem id="aomori">青森県</SelectItem>
  <SelectItem id="iwate">岩手県</SelectItem>
</Select>
```

## 構成要素

| 部品 | 役割 |
|---|---|
| Select | ラベル・補足説明・ドロップダウンを含む本体 |
| SelectItem | 個々の選択肢 |

## 使う場面

- 5 個以上の選択肢から 1 つを選ばせるとき（例：都道府県、国名）
- テーブル内など、スペースが限られる場所で 1 つを選ばせるとき

## 使い方

### 選択肢

- [should] 選択肢が 4 個以下の場合は、Select ではなく RadioGroup + Radio を使う。ただし、テーブル内など並べるスペースがない場合は Select を使ってよい
- [should] 選択肢の並び順は、利用頻度よりも予測しやすさを優先する（例：都道府県は北から南の順）
- [avoid] 複数選択に使わない。複数選択には Checkbox を並べる
- [avoid] 表示の切り替えやナビゲーションに使わない。表示の切り替えには Tabs を使う
- 選択肢の絞り込み（検索）には対応していない

### 初期値と未選択状態

- [should] 既存の値がある場合は、その値を初期値にする
- [should] 既存の値がない場合は、初期値を設定せず placeholder を表示する

### ラベルと補足説明

- [should] label で何を選ぶのかを示す
- [should] 選択基準や注意事項を伝えたい場合は caption を使う

### サイズと幅

- [should] テーブル内など、スペースが限られる場面では size="s" を使う
- [should] size="l" の入力要素やボタンと並べる場合は、size="l" にそろえる
- [should] 他の入力要素と幅をそろえたい場合は width を指定する（例：full）

### 状態

- [should] エラーは、何をどう直せばよいかが分かる文言で示す
- [should] 権限不足や他の選択に依存して変更できない場合は isDisabled を指定する

## アクセシビリティ

- [must] label を省略する場合は aria-label を付与する

## 実装

- [must] 各 SelectItem に一意の id を指定する。選択値（selectedKey、defaultSelectedKey）は id で扱う
- [should] 初期値は defaultSelectedKey（制御する場合は selectedKey と onSelectionChange）で指定する
- [should] エラーの文言は validate で返す。返した文言が Select の下に表示される
- [should] フォームで送信する場合は name を指定する

## Props（自動生成）

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

### Select

| 名前 | 型 | 既定値 | 説明 |
|---|---|---|---|
| label | string | - | セレクトのラベルテキスト |
| caption | string | - | ラベル下部の補足説明テキスト |
| placeholder | string | - | 未選択時のプレースホルダーテキスト |
| size | "s" \| "m" \| "l" | - | セレクトのサイズ |
| width | "auto" \| "full" \| "half" \| "third" | - | セレクトの幅 |
| 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. |
| isDisabled | boolean | - | Whether the input is disabled. |
| autoComplete | string | - | Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete). |
| name | string | - | The name of the input, used when submitting an HTML form. |
| 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). |
| selectionMode | "single" | 'single' | Whether single or multiple selection is enabled. |
| selectedKey | Key \| null | - | The currently selected key in the collection (controlled). @deprecated |
| defaultSelectedKey | Key | - | The initial selected key in the collection (uncontrolled). @deprecated |
| onSelectionChange | ((key: Key \| null) => void) | - | Handler that is called when the selection changes. @deprecated |
| isOpen | boolean | - | Sets the open state of the menu. |
| defaultOpen | boolean | - | Sets the default open state of the menu. |
| onOpenChange | ((isOpen: boolean) => void) | - | Method that is called when the open state of the menu changes. |
| disabledKeys | Iterable<Key> | - | The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with. |
| value | Key \| null | - | The current value (controlled). |
| defaultValue | Key \| null | - | The default value (uncontrolled). |
| onChange | ((value: Key \| null) => void) | - | Handler that is called when the value changes. |
| isRequired | boolean | - | Whether user input is required on the input before form submission. |
| isInvalid | boolean | - | Whether the input value is invalid. |
| validate | ((value: Key) => 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. |
| 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. |
| excludeFromTabOrder | boolean | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| className | ClassNameOrFunction<SelectRenderProps> | - | 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<SelectRenderProps> | - | 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. |

### SelectItem

| 名前 | 型 | 既定値 | 説明 |
|---|---|---|---|
| id | Key | - | The unique id of the item. |
| value | object | - | The object value that this item represents. When using dynamic collections, this is set automatically. |
| textValue | string | - | A string representation of the item's contents, used for features like typeahead. |
| aria-label | string | - | An accessibility label for this item. |
| isDisabled | boolean | - | Whether the item is disabled. |
| onAction | (() => void) | - | Handler that is called when a user performs an action on the item. The exact user event depends on the collection's `selectionBehavior` prop and the interaction modality. |
| children | ChildrenOrFunction<ListBoxItemRenderProps> | - | The children of the component. A function may be provided to alter the children based on component state. |
| className | ClassNameOrFunction<SelectRenderProps> | - | 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<SelectRenderProps> | - | 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. |
| href | string | - | A URL to link to. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href). |
| hrefLang | string | - | Hints at the human language of the linked URL. See[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#hreflang). |
| target | HTMLAttributeAnchorTarget | - | The target window for the link. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target). |
| rel | string | - | The relationship between the linked resource and the current page. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel). |
| download | string \| boolean | - | Causes the browser to download the linked URL. A string may be provided to suggest a file name. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download). |
| ping | string | - | A space-separated list of URLs to ping when the link is followed. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#ping). |
| referrerPolicy | "" \| "no-referrer" \| "no-referrer-when-downgrade" \| "origin" \| "origin-when-cross-origin" \| "same-origin" \| "strict-origin" \| "strict-origin-when-cross-origin" \| "unsafe-url" | - | How much of the referrer to send when following the link. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#referrerpolicy). |
| routerOptions | undefined | - | Options for the configured client side router. |
| 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. |