オートコンプリート

デフォルトでは、Autocomplete は、オプションリストに存在しない値をユーザーが指定することを許可せず、フォーカスが外れると入力値を現在選択されている値に戻します。allowsCustomValue を指定すると、この動作は抑制され、ユーザーはフィールド内に任意の値を入れることができます。

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

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

注: アイコンの回転を無効にするには、disableSelectorIconRotation プロパティを使用してください。

スクロールシャドウなし

Autocomplete コンポーネントは、内部で ScrollShadow を使用して、オートコンプリートの内容がスクロール可能である場合に影を表示します。この影は、scrollShadowProps プロパティを使用することで無効にできます。

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

説明付き

description プロパティを渡すことで、オートコンプリートに説明を追加できます。

エラーメッセージ付き

isInvalid プロパティと errorMessage プロパティを組み合わせることで、無効なオートコンプリートを表示できます。

Autocomplete コンポーネントは、マウス、キーボード、タッチによる選択をサポートしています。これらはすべて onSelectionChange プロパティで処理できます。Autocomplete は、選択されたキーを onSelectionChange ハンドラーに渡します。さらに、ComboBox は onInputChange プロパティを受け入れます。これは、タイピングやオプションの選択など、ユーザーが値を編集するたびにトリガーされます。

以下の例では、onSelectionChange と onInputChange を使用して、React の状態に格納された選択と入力値を更新します。

制御された状態

選択された値を制御するには、selectedKey プロパティと onSelectionChange プロパティを使用できます。

完全に制御された状態

inputValue、selectedKey、および items を Autocomplete に渡すことで、Autocomplete が表示する内容を正確に制御できます。

次の例は、選択された値 selectedKey からコンボボックスオプション items まで、すべてを制御する、制御された Autocomplete を作成する方法を示しています。

アイテムのフィルタリングを管理するには、@react-aria/i18n の useFilter フックを使用することをお勧めします。

npm install @react-aria/i18n

import {useFilter} from "@react-aria/i18n";

注: Autocomplete のすべての側面を制御する必要はないことに注意してください。Autocomplete の 1 つのプロパティのみを制御する場合は、そのプロパティの変更ハンドラーも必ず提供してください。例えば、selectedKey を制御するには、onSelectionChange が必要になります。

カスタムアイテム

AutocompleteItem の子を修正することで、オートコンプリートアイテムをカスタマイズできます。

カスタムの空コンテンツメッセージ

デフォルトでは、フィルターを使用したクエリに一致する結果がない場合、No results found. というメッセージが表示されます。 listboxProps の emptyContent を変更することで、空コンテンツメッセージをカスタマイズできます。

カスタムフィルタリング

デフォルトでは、Autocomplete は、オプションのリストをフィルタリングするために useFilter からの "contains" 関数を使用します。これは、defaultFilter プロパティを使用するか、items プロパティを使用してフィルタリングされたリストを制御することで上書きできます。defaultItems ではなく items が指定されている場合、Autocomplete 自体はフィルタリングを行いません。

次の例では、カスタムフィルタ関数を使用してオプションのリストをフィルタリングするために、defaultFilter プロパティを使用しています。

非同期フィルタリング

Autocomplete は非同期フィルタリングをサポートしています。以下の例では、useAsyncList 関数を react-aria から使用して、サーバーからのデータの非同期ロードとフィルタリングを処理しています。

npm install @react-stately/data

import {useAsyncList} from "@react-stately/data";

非同期ロード

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

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

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

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

base: オートコンプリートのメインラッパー。これは、入力コンポーネントとポップオーバーコンポーネントをラップします。
listboxWrapper: リストボックスのラッパー。これはリストボックスコンポーネントをラップし、このスロットはスクロールシャドウコンポーネントの上部で使用されます。
listbox: リストボックスコンポーネント。これはオートコンプリートアイテムをラップするコンポーネントです。
popoverContent: ポップオーバーコンテンツのスロット。ポップオーバーのコンテンツスタイルを変更するために使用します。
endContentWrapper: エンドコンテンツのラッパー。クリアボタンとセレクターボタンをラップします。
clearButton: クリアボタンのスロット。
selectorButton: セレクターボタンのスロット。

データ属性

Autocomplete の base 要素には、以下の属性があります。

data-invalid: オートコンプリートが無効な場合。isInvalid プロパティに基づきます。
data-open: オートコンプリートのポップオーバーが開いているかどうかを示します。

Autocomplete の selectorButton 要素には、以下の属性があります。

data-open: オートコンプリートのポップオーバーが開いているかどうかを示します。

Autocomplete の clearButton 要素には、以下の属性があります。

data-visible: オートコンプリートのクリアボタンが表示されるかどうかを示します。デフォルトでは、オートコンプリートにカーソルを合わせたとき、およびオートコンプリートに値があるとき（デスクトップ）、またはオートコンプリートに値があるとき（モバイル）に表示されます。

AutocompleteItem の base 要素には、以下の属性があります。

data-disabled: オートコンプリートの項目が無効な場合。オートコンプリートの disabledKeys プロパティに基づきます。
data-selected: オートコンプリートの項目が選択されている場合。オートコンプリートの selectedKey プロパティに基づきます。
data-hover: オートコンプリートの項目にカーソルが合わされている場合。useHoverに基づきます。
data-pressed: オートコンプリートの項目が押されている場合。usePressに基づきます。
data-focus: オートコンプリートの項目がフォーカスされている場合。useFocusRingに基づきます。
data-focus-visible: オートコンプリートの項目がキーボードでフォーカスされている場合。useFocusRingに基づきます。

アクセシビリティ

入力によるオプションリストのフィルタリングをサポート
単一のオプションの選択をサポート
無効なオプションのサポート
セクション内の項目のグループのサポート
カスタムユーザー入力値のサポート
制御されたオプションと制御されていないオプション、選択、入力値、およびオープン状態のサポート
カスタムフィルター関数のサポート
非同期ロードと無限スクロールのサポート
長いリストでのパフォーマンスのための仮想化スクロールのサポート
ARIAを使用したコンボボックスとして支援技術に公開
アクセシビリティのためのラベル付けのサポート
ARIAを介して支援技術に公開される必須および無効な状態
マウス、タッチ、およびキーボード操作のサポート
矢印キーを使用してコンボボックスのリストボックスを開くためのキーボードサポート。それに応じて最初または最後の項目を自動的にフォーカスすることを含む
入力時、フォーカス時、または手動でリストボックスを開くためのサポート
タッチスクリーンリーダーからの入力を仮想クリックして、リストボックスを切り替える
コンボボックスリストボックスのオプションナビゲーションのための仮想フォーカスマネジメント
リストボックスがポータルで開いている間、入力とリストボックスの外側の要素を支援技術から非表示にする
VoiceOverバグを回避するための、オプションのフォーカス、フィルタリング、および選択のためのカスタムローカライズされたアナウンス（ARIAライブリージョンを使用）
ARIAを介して入力にリンクされた説明とエラーメッセージのヘルプテキストのサポート

API

オートコンプリートのプロパティ

属性	型	説明	デフォルト
children*	`ReactNode[]`	レンダリングする子要素。通常は、`AutocompleteItem` および `AutocompleteSection` 要素のリストです。	-
label	`ReactNode`	ラベルとして表示するコンテンツ。	-
name	`string`	HTMLフォームを送信するときに使用される、入力要素の名前。MDNを参照してください。	-
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`	オートコンプリートの半径。	-
items	`Iterable<T>`	オートコンプリートのアイテムのリスト。（制御された状態）	-
defaultItems	`Iterable<T>`	オートコンプリートのアイテムのリスト（非制御）。	-
inputValue	`string`	オートコンプリートの入力値（制御された状態）。	-
defaultInputValue	`string`	オートコンプリートの入力値（非制御）。	-
allowsCustomValue	`boolean`	オートコンプリートが、アイテムに一致しない入力値を設定できるかどうか。	`false`
allowsEmptyCollection	`boolean`	コレクションが空のときに、オートコンプリートのメニューを開くことを許可するかどうか。	`true`
shouldCloseOnBlur	`boolean`	入力がフォーカスを失ったときに、オートコンプリートを閉じるかどうか。	`true`
placeholder	`string`	テキスト入力が空の場合に表示される一時的なテキスト。	-
description	`ReactNode`	フィールドの説明。選択する内容に関する具体的な要件などのヒントを提供します。	-
menuTrigger	`focus` \| `input` \| `manual`	メニューを開く原因となるアクション。	`focus`
labelPlacement	`inside` \| `outside` \| `outside-left`	ラベルの位置。	`inside`
selectedKey	`React.Key`	コレクション内で現在選択されているキー（制御された状態）。	-
defaultSelectedKey	`React.Key`	コレクション内で最初に選択されたキー（非制御）。	-
disabledKeys	`all` \| `React.Key[]`	無効になっているアイテムのキー。これらのアイテムは選択、フォーカス、またはその他の操作を行うことができません。	-
errorMessage	`ReactNode` \| `((v: ValidationResult) => ReactNode)`	フィールドの下に表示するエラーメッセージ。	-
validate	`(value: { inputValue: string, selectedKey: React.Key }) => ValidationError ｜ true ｜ null ｜ undefined`	コミット時（例：フォーカスが外れたとき）に入力値を検証し、無効な値のエラーメッセージを返します。	-
validationBehavior	`native` \| `aria`	値が不足しているか無効な場合にフォームの送信を防止するために、ネイティブのHTMLフォーム検証を使用するか、ARIAを介してフィールドを必須または無効としてマークするかどうか。	`aria`
startContent	`ReactNode`	オートコンプリートの左側にレンダリングされる要素。	-
endContent	`ReactNode`	オートコンプリートの右側にレンダリングされる要素。	-
autoFocus	`boolean`	オートコンプリートがレンダリング時にフォーカスされるかどうか。	`false`
defaultFilter	`(textValue: string, inputValue: string) => boolean`	オートコンプリートリストにオプションを含めるかどうかを決定するために使用されるフィルター関数。	-
filterOptions	Intl.CollatorOptions	フィルタリングに使用される照合器を作成するために使用されるオプション。	`{ sensitivity: 'base'}`
isReadOnly	`boolean`	オートコンプリートが読み取り専用かどうか。	`false`
isRequired	`boolean`	オートコンプリートが必須かどうか。	`false`
isInvalid	`boolean`	オートコンプリートが無効かどうか。	`false`
isDisabled	`boolean`	オートコンプリートが無効かどうか。	`false`
fullWidth	`boolean`	入力が親の幅を占めるかどうか。	`true`
selectorIcon	`ReactNode`	オートコンプリートのオープン状態を表すアイコン。通常はシェブロンアイコン。	-
clearIcon	`ReactNode`	クリアボタンで使用されるアイコン。通常はクロスアイコン。	-
showScrollIndicators	`boolean`	リストボックスがスクロール可能な場合に、スクロールインジケーターを表示するかどうか。	`true`
scrollRef	`React.RefObject<HTMLElement>`	スクロール可能な要素への参照。	-
inputProps	InputProps	Inputコンポーネントに渡すプロパティ。	-
popoverProps	PopoverProps	Popoverコンポーネントに渡すプロパティ。	-
listboxProps	ListboxProps	Listboxコンポーネントに渡すプロパティ。	-
scrollShadowProps	ScrollShadowProps	ScrollShadowコンポーネントに渡すプロパティ。	-
selectorButtonProps	ButtonProps	セレクターボタンに渡すプロパティ。	-
clearButtonProps	ButtonProps	クリアボタンに渡すプロパティ。	-
isClearable	`boolean`	クリアボタンを表示するかどうか。	`true`
disableClearable	`boolean`	クリアボタンを非表示にするかどうか。（非推奨）代わりに`isClearable`を使用してください。	`false`
disableAnimation	`boolean`	オートコンプリートをアニメーション化するかどうか。	`true`
disableSelectorIconRotation	`boolean`	選択でセレクターアイコンの回転を無効にするかどうか。	`false`
classNames	`Record<"base"｜ "listboxWrapper"｜ "listbox"｜ "popoverContent" ｜ "endContentWrapper"｜ "clearButton" ｜ "selectorButton", string>`	オートコンプリートのスロットにカスタムクラス名を設定できるようにします。	-

オートコンプリートイベント

属性	型	説明
onOpenChange	`(isOpen: boolean, menuTrigger?: MenuTriggerAction) => void`	メニューのオープン状態が変化したときに呼び出されるメソッド。新しいオープン状態と、メニューのオープンを引き起こしたアクションを返します。
onInputChange	`(value: string) => void`	オートコンプリートの入力値が変化したときに呼び出されるハンドラー。
onSelectionChange	`(key: React.Key) => void`	オートコンプリートの選択が変化したときに呼び出されるハンドラー。
onFocus	`(e: FocusEvent<HTMLInputElement>) => void`	オートコンプリートの入力にフォーカスが当たったときに呼び出されるハンドラー。
onBlur	`(e: FocusEvent<HTMLInputElement>) => void`	オートコンプリートの入力がフォーカスを失ったときに呼び出されるハンドラー。
onFocusChange	`(isFocused: boolean) => void`	オートコンプリートの入力フォーカスが変化したときに呼び出されるハンドラー。
onKeyDown	`(e: KeyboardEvent) => void`	キーが押されたときに呼び出されるハンドラー。
onKeyUp	`(e: KeyboardEvent) => void`	キーが離されたときに呼び出されるハンドラー。
onClose	`() => void`	オートコンプリートのPopoverが閉じられたときに呼び出されるハンドラー。

type MenuTriggerAction = "focus" | "input" | "manual";