Dropdown

Displays a list of actions or options that a user can choose.

---

Import

NextUI exports 5 dropdown-related components:

• Dropdown: The main component, which is a wrapper for the other components. This component is an extension of the Popover component, so it accepts all the props of the Popover component.
• DropdownTrigger: The component that triggers the dropdown menu to open.
• DropdownMenu: The component that contains the dropdown items.
• DropdownSection: The component that contains a group of dropdown items.
• DropdownItem: The component that represents a dropdown item.

Usage

Dynamic items

Dropdown follows the Collection Components API, accepting both static and dynamic collections.

• Static: The usage example above shows the static implementation, which can be used when the full list of options is known ahead of time.
• Dynamic: The example below can be used when the options come from an external data source such as an API call, or update over time.

Disabled Keys

Dropdown items can be disabled using the disabledKeys prop to the DropdownMenu component.

Note: It's important to have a unique key for each item, otherwise the disabled keys will not work.

Action event

You can use the onAction prop to get the key of the selected item.

Variants

You can use the variant in the DropdownMenu component to change the hover style of the dropdown items.

Single Selection

You can set the selectionMode property as single to allow the user to select only one item at a time.

Multiple Selection

You can set the selectionMode property as multiple to allow the user to select multiple items at a time.

Note: To allow empty selection, you can set the disallowEmptySelection property as false.

With Shortcut

You can use the shortcut prop to add a shortcut to the dropdown item.

Note: Dropdown does not handle the shortcut event, you need to handle it yourself.

With Icons

It is possible to add icons to the dropdown items using the startContent / endContent props.

Note: If you use currentColor as the icon color, the icon will have the same color as the item text.

With Description

You can use the description prop to add a description to the dropdown item.

With Sections

You can use the DropdownSection component to group dropdown items.

Note: Sections without a title must provide an aria-label for accessibility.

Custom Trigger

You can use any component as a trigger for the dropdown menu, just wrap it in the DropdownTrigger component.

Changing the backdrop

As we mentioned earlier, the Dropdown component is an extension of the Popover component, so it accepts all the props of the Popover component, including the backdrop prop.

Slots

Dropdown has 2 components with slots the DropdownItem and DropdownSection components.

DropdownItem

• base: The main slot for the dropdown item. It wraps all the other slots.
• wrapper: The title and description wrapper.
• title: The title of the dropdown item.
• description: The description of the dropdown item.
• shortcut: The shortcut slot.
• selectedIcon: The selected icon slot. This is only visible when the item is selected.

DropdownSection

• base: The main slot for the dropdown section. It wraps all the other slots.
• heading: The title that is render on top of the section group.
• group: The group of dropdown items.
• divider: The divider that is render between the groups. This is only visible when showDivider is true.

Customizing the dropdown popover

The Dropdown component is an extension of the Popover component, so you can use the same slots to customize the dropdown.

Customizing the dropdown items style

You can customize the dropdown items either by using the DropdownMenu itemClasses prop or by using the DropdownItem slots, the itemClasses allows you to customize all the items at once, while the slots allow you to customize each item individually.

Keyboard Interactions

Data Attributes

DropdownItem has the following attributes on the base element:

• data-disabled: When the dropdown item is disabled. Based on dropdown disabledKeys prop.
• data-selected: When the dropdown item is selected. Based on dropdown selectedKeys prop.
• data-hover: When the dropdown item is being hovered. Based on useHover
• data-pressed: When the dropdown item is pressed. Based on usePress
• data-focus: When the dropdown item is being focused. Based on useFocusRing.
• data-focus-visible: When the dropdown item is being focused with the keyboard. Based on useFocusRing.

Accessibility

• Exposed to assistive technology as a button with a menu using ARIA.
• Support for single, multiple, or no selection.
• Support for disabled items.
• Support for sections.
• Complex item labeling support for accessibility.
• Keyboard navigation support including arrow keys, home/end, page up/down. See Keyboard Interactions for more details.
• Automatic scrolling support during keyboard navigation.
• Keyboard support for opening the menu using the arrow keys, including automatically focusing the first or last item accordingly.
• Typeahead to allow focusing items by typing text.
• Virtualized scrolling support for performance with long lists.

API

Dropdown Props

Dropdown Events

---

DropdownTrigger Props

---

DropdownMenu Props

DropdownMenu Events

---

DropdownSection Props

---

DropdownItem Props

DropdownItem Events

---

Types

Dropdown Item Selected Icon Props

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;