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.

  • 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.
  • 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

KeyDescription
SpaceWhen focus is on DropdownTrigger, opens the dropdown menu and focuses the first item. When focus is on an item, activates the focused item.
EnterWhen focus is on DropdownTrigger, opens the dropdown menu and focuses the first item. When focus is on an item, activates the focused item.
ArrowDownWhen focus is on DropdownTrigger, opens the dropdown menu. When focus is on an item, moves focus to the next item.
ArrowUpWhen focus is on an item, moves focus to the previous item.
EscCloses the dropdown menu and moves focus to DropdownTrigger.
A-Z or a-zWhen the menu is open, moves focus to the next menu item with a label that starts with the typed character if such an menu item exists.

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

AttributeTypeDescriptionDefault
children*ReactNode[]The children to render. Usually a DropdownTrigger and DropdownMenu elements.-
typemenu | listboxType of overlay that is opened by the dropdown trigger.menu
triggerpress | longPressHow the dropdown menu is triggered.press
isDisabledbooleanWhether the dropdown trigger is disabled.false
closeOnSelectbooleanWhether the dropdown menu should be closed when an item is selected.true
shouldBlockScrollbooleanWhether the dropdown menu should block scrolling outside the menu.true
PopoverPropsPopoverPropsSince the dropdown is an extension of the popover, it accepts all the props of the popover component.-
AttributeTypeDescription
onOpenChange(isOpen: boolean) => voidHandler that is called when the dropdown's open state changes.
shouldCloseOnInteractOutside(e: HTMLElement) => voidWhen user interacts with the argument element outside of the dropdown ref, return true if onClose should be called.
onClose() => voidHandler that is called when the dropdown should close.

AttributeTypeDescriptionDefault
childrenReactNodeThe dropdown trigger component, ensure the children passed is focusable. Users can tab to it using their keyboard, and it can take a ref. It is critical for accessibility.-

AttributeTypeDescription
children*ReactNode | ((item: T) => ReactElement)The contents of the collection. It's usually the DropdownItem or DropdownSection. (static)-
itemsIterable<T>Item objects in the collection. (dynamic)-
variantsolid | bordered | light | flat | faded | shadowThe dropdown items appearance style.solid
colordefault | primary | secondary | success | warning | dangerThe dropdown items color theme.default
selectionModenone | single | multipleThe type of selection that is allowed in the collection.-
selectedKeysReact.Key[]The currently selected keys in the collection (controlled).-
disabledKeysReact.Key[]The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.-
defaultSelectedKeysall | React.Key[]The initial selected keys in the collection (uncontrolled).-
disallowEmptySelectionbooleanWhether the collection allows empty selection.false
autoFocusboolean | first | lastWhere the focus should be set.false
shouldFocusWrapbooleanWhether keyboard navigation is circular.false
closeOnSelectbooleanWhether the dropdown menu should be closed when an item is selected.true
disableAnimationbooleanWhether to disable the animation of the dropdown items.false
itemClassesRecord<"base"| "wrapper"| "title"| "description"| "shortcut" | "selectedIcon", string>Allows to set custom class names for the dropdown item slots.-
AttributeTypeDescription
onAction(key: React.Key) => voidHandler that is called when an item is selected.
onSelectionChange(keys: React.Key[]) => voidHandler that is called when the selection changes.
onClose() => voidHandler that is called when the menu should close after selecting an item.

AttributeTypeDescriptionDefault
children*ReactNodeThe contents of the dropdown section. Usually a list of DropdownItem components. (static)-
titlestringThe title of the dropdown section.-
itemsIterable<T>Item objects in the collection. (dynamic)-
showDividerbooleanWhether to show the divider between the groups.false
DividerPropsDividerPropsThe divider component props.-
classNamesRecord<"base"| "heading"| "group"| "divider", string>Allows to set custom class names for the dropdown section slots.-
itemClassesRecord<"base"| "wrapper"| "title"| "description"| "shortcut" | "selectedIcon", string>Allows to set custom class names for the dropdown item slots.-

AttributeTypeDescriptionDefault
children*ReactNodeThe contents of the dropdown item.-
keyReact.KeyThe unique key for the dropdown item.-
titlestring | ReactNodeThe title of the dropdown item.-
textValuestringA string representation of the item's contents, used for features like typeahead.-
descriptionstring | ReactNodeThe description of the dropdown item.-
shortcutstring | ReactNodeThe dropdown item keyboard shortcut.-
startContentReactNodeThe start content of the dropdown item.-
endContentReactNodeThe end content of the dropdown item. This is positioned after the shortcut and the selected icon.-
selectedIconSelectedIconPropsCustom icon to render when the item is selected.-
showDividerbooleanWhether to show a divider below the item.false
isDisabledbooleanWhether the dropdown item should be disabled. (Deprecated) pass disabledKeys to DropdownMenu instead.false
isSelectedbooleanWhether the dropdown item should be selected. (Deprecated) pass selectedKeys to DropdownMenu instead.false
isReadOnlybooleanWhether the dropdown item press events should be ignored.false
closeOnSelectbooleanWhether the dropdown menu should be closed when the item is selected.true
classNamesRecord<"base"| "wrapper"| "title"| "description"| "shortcut" | "selectedIcon", string>Allows to set custom class names for the dropdown item slots.-
AttributeTypeDescription
onAction() => voidHandler that is called when the dropdown item is selected. (Deprecated) pass to DropdownMenu instead.
onClose() => voidHandler that is called when the dropdown item should close after selecting. (Deprecated) pass to DropdownMenu instead.
onPress(e: PressEvent) => voidHandler called when the press is released over the target.
onPressStart(e: PressEvent) => voidHandler called when a press interaction starts.
onPressEnd(e: PressEvent) => voidHandler called when a press interaction ends, either over the target or when the pointer leaves the target.
onPressChange(isPressed: boolean) => voidHandler called when the press state changes.
onPressUp(e: PressEvent) => voidHandler called when a press is released over the target, regardless of whether it started on the target or not.
onKeyDown(e: KeyboardEvent) => voidHandler called when a key is pressed.
onKeyUp(e: KeyboardEvent) => voidHandler called when a key is released.
onClickMouseEventHandlerThe native button click event handler (Deprecated) use onPress instead.

Types

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;