リストボックス

import {Listbox, ListboxItem} from "@nextui-org/react";

function App() {
  return (
    <Listbox>
      <ListboxItem key="home" href="/home">
        Home
      </ListboxItem>
      <ListboxItem key="about" href="/about">
        About
      </ListboxItem>
    </Listbox>
  );
}

スロット

Listboxには、基本となる Listbox、ListboxItem、および ListboxSection の3つのコンポーネントにスロットがあります。

Listbox

base: listboxコンポーネントのメインラッパーです。このスロットは、topContent、bottomContent、および list スロットをラップします。
list: listboxコンポーネント用のスロットです。このスロットは ul スロットとして見ることができます。
emptyContent: コレクションが空の場合に表示するスロットコンテンツです。

ListboxItem

base: listboxアイテムのメインスロットです。他のすべてのスロットをラップします。
wrapper: title と description のラッパーです。
title: listboxアイテムのタイトルです。
description: listboxアイテムの説明です。
selectedIcon: 選択されたアイコンのスロットです。これは、アイテムが選択されている場合にのみ表示されます。

ListboxSection

base: listboxセクションのメインスロットです。他のすべてのスロットをラップします。
heading: セクショングループの上にレンダリングされるタイトルです。
group: listboxアイテムのグループです。
divider: グループ間にレンダリングされる区切り線です。これは、showDivider が true の場合にのみ表示されます。

Listboxのカスタマイズ

Listbox アイテムのスタイルは、itemClasses プロパティを使用し、カスタムのTailwind CSSクラスを渡すことでカスタマイズできます。

注意: 上記の例では、Boxicons アイコンコレクションを使用しています。

キーボード操作

キー	説明
`Home`	最初の項目にフォーカスを移動します。
`End`	最後の項目にフォーカスを移動します。
`ArrowDown`	項目にフォーカスがある場合、次の項目にフォーカスを移動します。
`ArrowUp`	項目にフォーカスがある場合、前の項目にフォーカスを移動します。
`Enter` または `Space`	項目にフォーカスがある場合、その項目を選択します。
`A-Z` または `a-z`	入力された文字で始まるラベルを持つ次のメニュー項目が存在する場合、そのメニュー項目にフォーカスを移動します。

データ属性

ListboxItem は、base 要素に以下の属性を持ちます。

data-disabled: リストボックス項目が無効になっている場合。リストボックスの disabledKeys プロパティに基づきます。
data-selected: リストボックス項目が選択されている場合。リストボックスの selectedKeys プロパティに基づきます。
data-selectable: リストボックス項目が選択可能な場合。リストボックスの selectionMode プロパティに基づきます。
data-hover: リストボックス項目がホバーされている場合。useHoverに基づきます。
data-pressed: リストボックス項目が押されている場合。usePressに基づきます。
data-focus: リストボックス項目がフォーカスされている場合。useFocusRingに基づきます。
data-focus-visible: リストボックス項目がキーボードでフォーカスされている場合。useFocusRingに基づきます。

アクセシビリティ

ARIA を使用して、支援技術に listbox として公開されます。
単一、複数、または選択なしをサポートします。
無効な項目をサポートします。
セクションをサポートします。
アクセシビリティのためのラベル付けをサポートします。
マウス、タッチ、キーボード操作をサポートします。
タブストップのフォーカスマネジメント。
矢印キー、Home/End、Page Up/Down、全選択、クリアなどのキーボードナビゲーションをサポートします。
キーボードナビゲーション中の自動スクロールをサポートします。
テキストを入力してオプションにフォーカスできるようにするタイプアヘッド。

API

リストボックスのプロパティ

属性	型	説明	デフォルト
children*	`ReactNode[]`	レンダリングする子要素。通常、`ListboxItem` または `ListboxSection` のリスト。	-
items	`Iterable<T>`	コレクション内の項目オブジェクト。（動的）	-
variant	`solid` \| `bordered` \| `light` \| `flat` \| `faded` \| `shadow`	リストボックス項目の外観スタイル。	`solid`
color	`default` \| `primary` \| `secondary` \| `success` \| `warning` \| `danger`	リストボックス項目のカラーテーマ。	`default`
selectionMode	`none` \| `single` \| `multiple`	コレクションで許可される選択の種類。	-
selectedKeys	`React.Key[]`	コレクションで現在選択されているキー（制御対象）。	-
disabledKeys	`React.Key[]`	無効になっている項目のキー。これらの項目は選択、フォーカス、その他の操作ができません。	-
defaultSelectedKeys	`all` \| `React.Key[]`	コレクションで最初に選択されたキー（非制御）。	-
disallowEmptySelection	`boolean`	コレクションが空の選択を許可するかどうか。	`false`
shouldHighlightOnFocus	`boolean`	フォーカスされた項目をハイライト表示するかどうか。ホバー時と同じスタイルが項目に適用されます。	`false`
autoFocus	`boolean` \| `first` \| `last`	フォーカスを設定する場所。	`false`
topContent	`ReactNode`	リストボックス項目の上に表示するコンテンツ。	-
bottomContent	`ReactNode`	リストボックス項目の下に表示するコンテンツ。	-
emptyContent	`ReactNode`	コレクションが空の場合に表示するコンテンツ。	`項目がありません。`
shouldFocusWrap	`boolean`	キーボードナビゲーションが循環するかどうか。	`false`
hideEmptyContent	`boolean`	コレクションが空の場合に空のコンテンツを表示しないかどうか。	`false`
hideSelectedIcon	`boolean`	項目が選択されている場合にチェックアイコンを非表示にするかどうか。	`false`
disableAnimation	`boolean`	リストボックス項目のアニメーションを無効にするかどうか。	`false`
classNames	`Record<"base"｜ "list"｜ "emptyContent", string>`	リストボックススロットのカスタムクラス名を設定できます。	-
itemClasses	`Record<"base"｜ "wrapper"｜ "title"｜ "description"｜ "selectedIcon", string>`	リストボックス項目のスロットのカスタムクラス名を設定できます。	-

リストボックスのイベント

属性	型	説明
onAction	`(key: React.Key) => void`	項目が選択されたときに呼び出されるハンドラー。
onSelectionChange	`(keys: React.Key[]) => void`	選択が変更されたときに呼び出されるハンドラー。

ListboxSection のプロパティ

属性	型	説明	デフォルト
children*	`ReactNode`	リストボックスセクションの内容。通常は、`ListboxItem` コンポーネントのリスト。（静的）	-
title	`string`	リストボックスセクションのタイトル。	-
items	`Iterable<T>`	コレクション内の項目オブジェクト。（動的）	-
hideSelectedIcon	`boolean`	項目が選択されている場合にチェックアイコンを非表示にするかどうか。	`false`
showDivider	`boolean`	グループ間に区切り線を表示するかどうか。	`false`
dividerProps	DividerProps	区切り線コンポーネントのプロパティ。	-
classNames	`Record<"base"｜ "heading"｜ "group"｜ "divider", string>`	リストボックスセクションのスロットにカスタムクラス名をセットできます。	-
itemClasses	`Record<"base"｜ "wrapper"｜ "title"｜ "description"｜ "shortcut" ｜ "selectedIcon", string>`	リストボックス項目のスロットのカスタムクラス名を設定できます。	-

ListboxItem Props

属性	型	説明	デフォルト
children*	`ReactNode`	リストボックスアイテムの内容。	-
key	`React.Key`	リストボックスアイテムの一意のキー。	-
title	`string` \| `ReactNode`	リストボックスアイテムのタイトル。	-
textValue	`string`	タイプアヘッドなどの機能に使用される、アイテムの内容の文字列表現。	-
description	`string` \| `ReactNode`	リストボックスアイテムの説明。	-
shortcut	`string` \| `ReactNode`	リストボックスアイテムのキーボードショートカット。	-
startContent	`ReactNode`	リストボックスアイテムの先頭コンテンツ。	-
endContent	`ReactNode`	リストボックスアイテムの末尾コンテンツ。ショートカットと選択されたアイコンの後に配置されます。	-
selectedIcon	SelectedIconProps	アイテムが選択されたときにレンダリングするカスタムアイコン。	-
href	`string`	リンク先のURL。MDNを参照してください。	-
target	`HTMLAttributeAnchorTarget`	リンクのターゲットウィンドウ。MDNを参照してください。	-
rel	`string`	リンクされたリソースと現在のページの関係。MDNを参照してください。	-
download	`boolean` \| `string`	リンクされたURLをブラウザにダウンロードさせます。ファイル名を提案するために文字列を指定できます。MDNを参照してください。	-
ping	`string`	リンクをたどるときにpingを送信するURLのスペース区切りリスト。MDNを参照してください。	-
referrerPolicy	`HTMLAttributeReferrerPolicy`	リンクをたどるときに送信するリファラーの量。MDNを参照してください。	-
shouldHighlightOnFocus	`boolean`	フォーカスされたアイテムをハイライト表示するかどうか。ホバー時と同じスタイルがアイテムに適用されます。	`false`
hideSelectedIcon	`boolean`	アイテムが選択されているときにチェックアイコンを非表示にするかどうか。	`false`
showDivider	`boolean`	アイテムの下に区切り線を表示するかどうか。	`false`
isDisabled	`boolean`	リストボックスアイテムを無効にするかどうか。（非推奨）代わりに`Listbox`にdisabledKeysを渡してください。	`false`
isSelected	`boolean`	リストボックスアイテムを選択する必要があるかどうか。（非推奨）代わりに`Listbox`にselectedKeysを渡してください。	`false`
isReadOnly	`boolean`	リストボックスアイテムの押下イベントを無視するかどうか。	`false`
classNames	`Record<"base"｜ "wrapper"｜ "title"｜ "description"｜ "shortcut" ｜ "selectedIcon", string>`	リストボックス項目のスロットのカスタムクラス名を設定できます。	-

ListboxItem Events

属性	型	説明
onAction	`() => void`	リストボックスアイテムが選択されたときに呼び出されるハンドラー。（非推奨）代わりに`Listbox`に渡してください。
onPress	`(e: PressEvent) => void`	ターゲット上でプレスが解除されたときに呼び出されるハンドラー。
onPressStart	`(e: PressEvent) => void`	プレスインタラクションが開始されたときに呼び出されるハンドラー。
onPressEnd	`(e: PressEvent) => void`	プレスインタラクションが終了したときに呼び出されるハンドラー。ターゲット上またはポインターがターゲットを離れたときです。
onPressChange	`(isPressed: boolean) => void`	プレス状態が変更されたときに呼び出されるハンドラー。
onPressUp	`(e: PressEvent) => void`	プレスがターゲット上でリリースされたときに呼び出されるハンドラー。ターゲット上で開始されたかどうかに関係なく。
onKeyDown	`(e: KeyboardEvent) => void`	キーが押されたときに呼び出されるハンドラー。
onKeyUp	`(e: KeyboardEvent) => void`	キーがリリースされたときに呼び出されるハンドラー。
onClick	`MouseEventHandler`	ネイティブボタンのクリックイベントハンドラー（非推奨）代わりにonPressを使用してください。

Types

リストボックスアイテムの選択アイコンプロパティ

export type ListboxItemSelectedIconProps = {
  /**
   * The current icon, usually an checkmark icon.
   */
  icon?: ReactNode;
  /**
   * The current selected status.
   */
  isSelected?: boolean;
  /**
   * The current disabled status.
   * @default false
   */
  isDisabled?: boolean;
};

type selectedIcon?: ReactNode | ((props: ListboxItemSelectedIconProps) => ReactNode) | null;