選択

選択は、折りたたみ可能なオプションのリストを表示し、ユーザーがそれらの中から1つ以上を選択できるようにします。

Storybook @nextui-org/select React Aria ソーススタイルのソース

インストール

npx nextui-cli@latest add select

上記のコマンドは、個別インストール専用です。もし、 @nextui-org/react がグローバルにインストール済みであれば、このステップはスキップできます。

インポート

NextUI は、セレクト関連のコンポーネントを 3 つエクスポートします。

Select: メインコンポーネントで、他のコンポーネントのラッパーです。
SelectSection: セレクトアイテムのグループを格納するコンポーネントです。
SelectItem: セレクトアイテムを表すコンポーネントです。

使い方

動的なアイテム

Select は、Collection Components API に従い、静的および動的なコレクションの両方を受け入れます。

静的: 上記の使用例は、静的な実装を示しており、オプションの完全なリストが事前にわかっている場合に使用できます。
動的: 下記の例は、オプションが API 呼び出しなどの外部データソースから取得される場合や、時間の経過とともに更新される場合に使用できます。

複数選択

複数選択を許可するには、selectionMode="multiple" プロパティを使用できます。

無効化

無効なアイテム

disabledKeys プロパティを使用することで、特定のアイテムを無効にできます。

必須

セレクトに isRequired プロパティを渡すと、ラベルの最後に danger アスタリスクが表示され、セレクトは必須になります。

サイズ

色

バリアント

半径

ラベルの配置

labelPlacement プロパティを inside、outside、または outside-left に設定することで、ラベルの位置を変更できます。

注意: label が渡されない場合、labelPlacement プロパティはデフォルトで outside になります。

開始コンテンツ

startContent プロパティと endContent プロパティを使用して、セレクトの先頭と末尾にコンテンツを追加できます。

アイテムの開始/終了コンテンツ

Select コンポーネントは内部で Listbox コンポーネントを使用しているため、SelectItem コンポーネントの startContent プロパティと endContent プロパティを使用して、セレクトアイテムの先頭と末尾にコンテンツを追加できます。

カスタムセレクターアイコン

デフォルトでは、セレクトはセレクターアイコンとして chevron-down アイコンを使用し、セレクトが開くと回転します。カスタムアイコンを selectorIcon プロパティに渡すことで、このアイコンをカスタマイズできます。

注意: アイコンの回転を無効にするには、disableSelectorIconRotation プロパティを使用します。

スクロールシャドウなし

セレクトコンポーネントは内部で ScrollShadow を使用して、セレクトコンテンツがスクロール可能な場合にシャドウを表示します。 scrollShadowProps プロパティを使用することで、このシャドウを無効にできます。

注意: showScrollIndicators プロパティを使用して、スクロールインジケーターを無効にすることもできます。

説明付き

description プロパティを渡すことで、セレクトに説明を追加できます。

エラーメッセージ付き

isInvalid プロパティと errorMessage プロパティを組み合わせることで、無効なセレクトを表示できます。

制御された

selectedKeys プロパティと onSelectionChange / onChange プロパティを使用して、選択値を制御できます。

onSelectionChange の使用

onChange の使用

開閉状態の制御

isOpen プロパティと onOpenChange / onClose プロパティを使用して、セレクトの開閉状態を制御できます。

カスタムアイテム

SelectItem の子要素を変更することで、セレクトアイテムをカスタマイズできます。

カスタムレンダリング値

デフォルトでは、セレクトは選択されたアイテムのテキスト値をレンダリングしますが、renderValue 関数を渡すことで、これをカスタマイズできます。

renderValue 関数は、選択されたアイテムをパラメーターとして受け取り、ReactNode を返す必要があります。詳細については、「レンダリング値関数」セクションを参照してください。

非同期読み込み

セレクトは非同期読み込みをサポートしています。以下の例では、カスタムフックを使用して、Pokemon API データを取得し、useInfiniteScroll フックと組み合わせて、ユーザーがリストの最後に到達したときにさらにデータをロードしています。

isLoading プロパティは、データの取得中にセレクターアイコンの代わりにローディングインジケーターを表示するために使用されます。

npm install @nextui-org/use-infinite-scroll

import {useInfiniteScroll} from "@nextui-org/use-infinite-scroll";

セクション付き

SelectSection コンポーネントを使用して、セレクトアイテムをグループ化できます。

カスタムセクションスタイル

SelectSection コンポーネントの classNames プロパティを使用すると、セクションのスタイルをカスタマイズできます。

複数選択の制御

単一選択と同じプロパティを使用して、複数選択を制御できます。selectedKeys および onSelectionChange / onChange。

onSelectionChange の使用

onChange の使用

チップ付き複数選択

renderValue プロパティを使用すると、任意のコンポーネントを選択値としてレンダリングできます。この例では、選択されたアイテムをレンダリングするために Chip コンポーネントを使用しています。

注: チップを折り返せるようにするには、Select コンポーネントに isMultiline プロパティを必ず渡してください。

セレクトのカスタマイズ

selectのどのスロットも、classNamesプロパティを使ってカスタマイズできます。selectコンポーネントは、ポップオーバーとリストボックスのコンポーネントをカスタマイズするために、popoverPropsとlistboxPropsプロパティも提供しています。

スロット

base: selectのメインのラッパー。残りのスロットをラップします。
label: selectのラベル。
mainWrapper: helperWrapperとtriggerスロットをラップします。
trigger: selectのトリガー。ラベル、インナーラッパー、セレクターアイコンをラップします。
innerWrapper: selectコンテンツのラッパー。開始/終了コンテンツとselectの値をラップします。
selectorIcon: selectのセレクターアイコン。selectが開いているときに回転するアイコンです(data-open)。
value: selectの値。renderValue関数の結果をラップするスロットでもあります。
listboxWrapper: リストボックスのラッパー。リストボックスコンポーネントをラップします。このスロットはスクロールシャドウコンポーネントの上部で使用されます。
listbox: リストボックスコンポーネント。selectアイテムをラップするコンポーネントです。
popoverContent: ポップオーバーコンテンツスロット。ポップオーバーコンテンツのスタイルを変更するために使用します。
helperWrapper: ヘルパーテキストのラッパー。ヘルパーテキストとエラーメッセージをラップします。
description: selectの説明。
errorMessage: selectのエラーメッセージ。

データ属性

Selectには、base要素に次の属性があります

data-filled: selectに値があるか、フォーカスされているか、開始/終了コンテンツがあるか、または開いているかを示します。
data-has-value: selectに選択されたアイテムがあるかを示します。
data-has-label: selectにラベルがあるかを示します。labelプロップに基づきます。
data-has-helper: selectにヘルパーテキストがあるかを示します。errorMessageまたはdescriptionプロップに基づきます。
data-invalid: selectが無効かどうかを示します。isInvalidプロップに基づきます。

Selectには、trigger要素に次の属性があります

data-open: selectが開いているかを示します。
data-disabled: selectトリガーが無効になっている場合。selectのisDisabledプロップに基づきます。
data-focus: selectトリガーがフォーカスされている場合。useFocusRingに基づきます。
data-focus-visible: selectトリガーがキーボードでフォーカスされている場合。useFocusRingに基づきます。
data-pressed: selectトリガーが押された場合。usePressに基づきます。
data-hover: selectトリガーがホバーされている場合。useHoverに基づきます。

Selectには、selectorIcon要素に次の属性があります

data-open: selectが開いているかを示します。

SelectItemには、base要素に次の属性があります

data-disabled: selectアイテムが無効になっている場合。selectのdisabledKeysプロップに基づきます。
data-selected: selectアイテムが選択されている場合。selectのselectedKeysプロップに基づきます。
data-hover: selectアイテムがホバーされている場合。useHoverに基づきます。
data-pressed: 選択された項目が押されたとき。 usePress に基づきます。
data-focus: 選択された項目がフォーカスされているとき。 useFocusRing に基づきます。
data-focus-visible: 選択された項目がキーボードでフォーカスされているとき。 useFocusRing に基づきます。

アクセシビリティ

ARIA を使用したリストボックスポップアップを持つボタンとして支援技術に公開されます（リストボックスと組み合わせて）。
単一オプションの選択をサポートします。
複数オプションの選択をサポートします。
無効化されたオプションをサポートします。
セクションをサポートします。
アクセシビリティのためのラベル付けをサポートします。
ARIA を介して入力にリンクされた説明とエラーメッセージのヘルプテキストをサポートします。
マウス、タッチ、キーボードの操作をサポートします。
タブストップのフォーカス管理。
矢印キーを使用したリストボックスの展開のキーボードサポート。最初のまたは最後の項目に応じて自動的にフォーカスすることも含みます。
タイプアヘッドにより、リストボックスを開かなくてもテキストを入力してオプションを選択できます。
隠されたネイティブの <select> 要素によるブラウザの自動補完統合。
ソフトウェアキーボードによるモバイルフォームナビゲーションのサポート。
モバイルスクリーンリーダーのリストボックスの却下サポート。

API

選択プロパティ

属性	型	説明	デフォルト
children*	`ReactNode[]`	レンダリングする子。通常、`SelectItem` および `SelectSection` 要素のリストです。	-
items	`Iterable<T>`	選択内の項目オブジェクト。（動的）	-
selectionMode	`single` \| `multiple`	コレクションで許可される選択の種類。	-
selectedKeys	`all` \| `React.Key[]`	コレクションで現在選択されているキー（制御付き）。	-
disabledKeys	`all` \| `React.Key[]`	無効化されている項目キー。これらの項目は選択、フォーカス、その他の操作を行うことはできません。	-
defaultSelectedKeys	`all` \| `React.Key[]`	コレクションで最初に選択されたキー（非制御）。	-
variant	`flat` \| `bordered` \| `faded` \| `underlined`	選択のバリアント。	`flat`
color	`default` \| `primary` \| `secondary` \| `success` \| `warning` \| `danger`	選択の色。	`default`
size	`sm` \| `md` \| `lg`	選択のサイズ。	`md`
radius	`none` \| `sm` \| `md` \| `lg` \| `full`	選択の半径。	-
placeholder	`string`	選択のプレースホルダー。	`オプションを選択`
labelPlacement	`inside` \| `outside` \| `outside-left`	ラベルの位置。	`inside`
label	`ReactNode`	ラベルとして表示するコンテンツ。	-
description	`ReactNode`	選択の説明。選択内容に関する特定の要件などのヒントを提供します。	-
errorMessage	`ReactNode` \| `((v: ValidationResult) => ReactNode)`	選択のエラーメッセージ。	-
startContent	`ReactNode`	選択の左側にレンダリングする要素。	-
endContent	`ReactNode`	選択の右側にレンダリングする要素。	-
selectorIcon	`ReactNode`	セレクターアイコンとしてレンダリングする要素。	-
scrollRef	`React.RefObject<HTMLElement>`	スクロール可能な要素への参照。	-
spinnerRef	`React.RefObject<HTMLElement>`	スピナー要素への参照。	-
fullWidth	`boolean`	選択が親の幅を占めるかどうか。	`true`
isOpen	`boolean`	選択がデフォルトで開いているかどうか（制御付き）。	-
defaultOpen	`boolean`	選択がデフォルトで開いているかどうか（非制御）。	-
isRequired	`boolean`	フォーム送信前に選択でユーザーの選択が必要かどうか。	`false`
isDisabled	`boolean`	選択が無効化されているかどうか。	`false`
isMultiline	`boolean`	選択が複数行のテキストを許可するかどうか。	`false`
isInvalid	`boolean`	選択が無効かどうか。	`false`
validationState	`valid` \| `invalid`	選択が「有効」または「無効」の視覚スタイルを表示するかどうか（非推奨）。代わりにisInvalidを使用してください。	-
showScrollIndicators	`boolean`	リストボックスがスクロール可能な場合に、選択がスクロールインジケーターを表示するかどうか。	`true`
autoFocus	`boolean`	選択が最初のマウントでフォーカスされるかどうか。	`false`
disallowEmptySelection	`boolean`	コレクションが空の選択を許可するかどうか。	`false`
disableAnimation	`boolean`	セレクトをアニメーション化するかどうか。	`true`
disableSelectorIconRotation	`boolean`	セレクトのセレクターアイコンの回転を無効にするかどうか。	`false`
popoverProps	PopoverProps	ポップオーバーコンポーネントに渡される props。	-
listboxProps	ListboxProps	リストボックスコンポーネントに渡される props。	-
scrollShadowProps	ScrollShadowProps	スクロールシャドウコンポーネントに渡される props。	-
classNames	`Record<"base"｜ "label"｜ "trigger"｜ "mainWrapper" ｜ "innerWrapper"｜ "selectorIcon" ｜ "value" ｜ "listboxWrapper"｜ "listbox" ｜ "popoverContent" ｜ "helperWrapper" ｜ "description" ｜ "errorMessage", string>`	Select のスロットにカスタムクラス名を指定できます。	-

Select イベント

属性	型	説明
onClose	`() => void`	セレクトポップオーバーが閉じられたときに発火するコールバック。
onOpenChange	`(isOpen: boolean) => void`	セレクトポップオーバーが開閉されたときに発火するコールバック。
onSelectionChange	`(keys: React.Key[]) => void`	選択されたキーが変更されたときに発火するコールバック。
onChange	`React.ChangeEvent<HTMLSelectElement>`	選択された値が変更されたときに発火する、ネイティブのセレクト変更イベント。
renderValue	RenderValueFunction	セレクトの値をレンダリングする関数。デフォルトでは、選択されたアイテムをレンダリングします。

export type SelectedItemProps<T> = {
  /** A unique key for the item. */
  key?: Key;
  /** The props passed to the item. */
  props?: Record<string, any>;
  /** The item data. */
  data?: T | null;
  /** An accessibility label for this item. */
  "aria-label"?: string;
  /** The rendered contents of this item (e.g. JSX). */
  rendered?: ReactNode;
  /** A string value for this item, used for features like typeahead. */
  textValue?: string;
  /** The type of item this item represents. */
  type?: string;
};

type SelectedItems<T> = Array<SelectedItemProps<T>>;

renderValue: (items: SelectedItems<T>) => ReactNode;