ドロップダウン

ユーザーが選択できるアクションやオプションのリストを表示します。

インストール

npx nextui-cli@latest add dropdown

上記のコマンドは、個別のインストールのみを対象としています。もし、 @nextui-org/react がグローバルにインストールされている場合は、このステップをスキップできます。

インポート

NextUI は、ドロップダウン関連の 5 つのコンポーネントをエクスポートします。

• Dropdown: メインのコンポーネントで、他のコンポーネントのラッパーです。このコンポーネントは、Popover コンポーネントの拡張であり、Popover コンポーネントのすべての props を受け入れます。
• DropdownTrigger: ドロップダウンメニューを開くトリガーとなるコンポーネントです。
• DropdownMenu: ドロップダウンアイテムを含むコンポーネントです。
• DropdownSection: ドロップダウンアイテムのグループを含むコンポーネントです。
• DropdownItem: ドロップダウンアイテムを表すコンポーネントです。

使用方法

動的なアイテム

ドロップダウンは、Collection Components APIに従い、静的コレクションと動的コレクションの両方を受け入れます。

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

無効なキー

ドロップダウンアイテムは、disabledKeys prop を DropdownMenu コンポーネントに渡すことで無効にできます。

注: 各アイテムに一意のキーを設定することが重要です。そうしないと、無効なキーが機能しません。

アクションイベント

onAction prop を使用すると、選択したアイテムのキーを取得できます。

バリアント

DropdownMenu コンポーネントの variant を使用すると、ドロップダウンアイテムの hover スタイルを変更できます。

単一選択

ユーザーが一度に1つのアイテムのみを選択できるようにするには、selectionMode プロパティを single に設定します。

複数選択

ユーザーが一度に複数のアイテムを選択できるようにするには、selectionMode プロパティを multiple に設定します。

注意: 空の選択を許可するには、disallowEmptySelection プロパティを false に設定します。

ショートカット付き

ドロップダウン項目にショートカットを追加するには、shortcut プロパティを使用できます。

注意: ドロップダウンはショートカットイベントを処理しません。自分で処理する必要があります。

アイコン付き

startContent / endContent プロパティを使用して、ドロップダウン項目にアイコンを追加できます。

注意: アイコンの色として currentColor を使用すると、アイコンは項目テキストと同じ色になります。

説明付き

ドロップダウン項目に説明を追加するには、description プロパティを使用できます。

セクション付き

ドロップダウン項目をグループ化するには、DropdownSection コンポーネントを使用できます。

注意: title のないセクションは、アクセシビリティのために aria-label を提供する必要があります。

カスタムトリガー

ドロップダウンメニューのトリガーとして任意のコンポーネントを使用できます。それらを DropdownTrigger コンポーネントでラップするだけです。

背景の変更

前述したように、Dropdown コンポーネントは Popover コンポーネントの拡張であるため、backdrop プロパティを含む、Popover コンポーネントのすべてのプロパティを受け入れます。

ルーティング

<DropdownItem> コンポーネントは、Next.js や React Router のようなフレームワークやクライアントサイドルーターで動作します。設定方法については、ルーティングガイドを参照してください。

import {Dropdown, DropdownMenu, DropdownTrigger, DropdownItem, Button} from "@nextui-org/react";

function App() {
  return (
    <Dropdown>
      <DropdownTrigger>
        <Button variant="bordered">Open Menu</Button>
      </DropdownTrigger>
      <DropdownMenu aria-label="Link Actions">
        <DropdownItem key="home" href="/home">
          Home
        </DropdownItem>
        <DropdownItem key="about" href="/about">
          About
        </DropdownItem>
      </DropdownMenu>
    </Dropdown>
  );
}

スロット

ドロップダウンには、DropdownMenu, DropdownItem, DropdownSection の3つのコンポーネントにスロットがあります。

DropdownMenu

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

DropdownItem

• base: ドロップダウンアイテムのメインスロット。他のすべてのスロットをラップします。
• wrapper: title および description のラッパー。
• title: ドロップダウンアイテムのタイトル。
• description: ドロップダウンアイテムの説明。
• shortcut: ショートカットスロット。
• selectedIcon: 選択されたアイコンスロット。アイテムが選択されている場合にのみ表示されます。

DropdownSection

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

ドロップダウンポップオーバーのカスタマイズ

Dropdown コンポーネントは、Popover コンポーネントの拡張であるため、同じスロットを使用してドロップダウンをカスタマイズできます。

ドロップダウンアイテムのスタイルのカスタマイズ

DropdownMenu の itemClasses プロパティを使用するか、DropdownItem スロットを使用するかで、ドロップダウンアイテムをカスタマイズできます。itemClasses を使用すると、すべてのアイテムを一度にカスタマイズできますが、スロットを使用すると、各アイテムを個別にカスタマイズできます。

キーボード操作

データ属性

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

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

アクセシビリティ

• 支援技術に対して、ARIA を使用した button と menu として公開されます。
• 単一、複数、または選択なしのサポート。
• 無効化された項目のサポート。
• セクションのサポート。
• アクセシビリティのための複雑な項目ラベルのサポート。
• 矢印キー、Home/End、Page Up/Down を含むキーボードナビゲーションのサポート。詳細については、キーボード操作を参照してください。
• キーボードナビゲーション中の自動スクロールのサポート。
• 矢印キーを使用してメニューを開くためのキーボードサポート（最初の項目または最後の項目に自動的にフォーカスを含む）。
• テキストを入力して項目にフォーカスできるようにするタイプアヘッド。
• 長いリストでのパフォーマンスのための仮想化スクロールのサポート。

API

ドロップダウンのプロパティ

ドロップダウンイベント

DropdownTrigger のプロパティ

DropdownMenu のプロパティ

DropdownMenu Events

DropdownSection Props

DropdownItem Props

DropdownItem イベント

型

ドロップダウンアイテム選択済みアイコンのプロパティ

export type DropdownItemSelectedIconProps = {
  /**
   * 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: DropdownItemSelectedIconProps) => ReactNode) | null;