Dropdown

Displays a list of actions or options that a user can choose. Dropdown implementation is based on
@react-aria/menu

import { Dropdown } from '@nextui-org/react';

Anatomy

  • Dropdown: The wrapper that provides state, context and focus management.
  • Dropdown.Trigger: Used to wrap the reference (or trigger) element.
  • Dropdown.Button: A NextUI Button component used as the trigger (includes a chevron icon).
  • Dropdown.Menu: The wrapper for the items. Must be a direct child of Dropdown.
  • Dropdown.Item: The individual items. Must be a direct child of Dropdown.Menu.
  • Dropdown.Section: A wrapper to group related menu items.

Static

Static collections, as in this example, can be used when the full list of items is known ahead of time.

The Dropdown can be closed by clicking or interacting outside the popover, or by pressing the Escape key. When the popover is closed, focus is restored back to its trigger button.

Dynamic

Dynamic collections, as shown below, can be used when the items come from an external data source such as an API call, or update over time. Providing the data in this way allows for Menu to automatically cache the rendering of each item, which dramatically improves performance.

Divider

Dropdown items include a prop called withDivider that can be used to separate items in the menu.

Disabled Keys

You can disable specific rows by providing an array of keys to Dropdown.Menu through the disabledKeys prop. This will prevent items from being selectable as shown in the example below.

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

Variants

Dropdown can be styled with different variants. The default variant is flat, but you can also use light, solid and shadow.

Single selection

You can set the selectionMode property as single to limit users to select only a single item at a time.

Multiple selection

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

Command

Dropdown items support adding commands (or hotkeys), you can use the command prop.

Icons

Dropdown items can include icons, you can use the icon prop.

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

Description

Dropdown items can include descriptions, you can use the description prop.

Sections

Dropdown supports sections in order to group options. Sections can be used by wrapping groups of Items in a Section component. Each Section takes a title and key prop.

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

Custom Trigger

Dropdown trigger can be mixed with other components like Avatar or User.

Disable animation

Disables the animation of the dropdown and its items when it is opened or closed.

Keyboard Interactions

KeyDescription
SpaceWhen focus is on DropdownMenu.Trigger or Dropdown.Button, opens the dropdown menu and focuses the first item. When focus is on an item, activates the focused item.
EnterWhen focus is on DropdownMenu.Trigger or Dropdown.Button, opens the dropdown menu and focuses the first item. When focus is on an item, activates the focused item.
ArrowDownWhen focus is on DropdownMenu.Trigger or Dropdown.Button, 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 DropdownMenu.Trigger or Dropdown.Button.
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.

APIs

AttributeTypeDescriptionDefault
children*ReactNode[]The content of the dropdown. It's usually the Dropdown.Trigger, Dropdown.Button and Dropdown.Menu.-
typeTriggerTypeThe type of dropdown menu that the dropdown trigger opens.menu
triggerMenuTriggerTypeHow the dropdown menu is triggered.press
closeOnSelectbooleanWhether the dropdown menu closes when a selection is made.true
isDisabledbooleanWhether dropdown trigger is disabled.false
PopoverPropsPopoverPropsSince dropdown is based on the Popover you can use any of the Popover props.-
AttributeTypeDescriptionDefault
PopoverEventsPopoverEventsSince dropdown is based on the Popover you can use any of the Popover events.-

AttributeTypeDescriptionDefault
children*ReactNodeThe 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 accessiblity.-

AttributeTypeDescriptionDefault
ButtonPropsButtonPropsSince dropdown button is based on the Button you can use any of the Button props.-

AttributeTypeDescriptionDefault
children*CollectionChildrentypeThe contents of the collection. It's usually the Dropdown.Item or Dropdown.Section.-
itemsIterable<T>Item objects in the collection.-
selectedKeysall Iterable<T>The currently selected keys in the collection (controlled).-
defaultSelectedKeysall Iterable<T>The initial selected keys in the collection (uncontrolled).-
disabledKeysIterable<T>The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.-
selectionModeSelectionModeTypeThe type of selection that is allowed in the collection.-
isVirtualizedbooleanWhether the dropdown menu uses virtual scrolling.false
disallowEmptySelectionbooleanWhether the collection allows empty selection.false
autoFocusboolean FocusStrategyTypeWhere the focus should be set.false
shouldFocusWrapbooleanWhether keyboard navigation is circular.false
keyboardDelegateKeyboardDelegateTypeAn optional keyboard delegate implementation for type to select, to override the default.-
colorSimpleColorsThe dropdown menu items colordefault
textColorSimpleColorsThe dropdown menu items text colordefault
variantDropdownVariantThe dropdown menu items variantionflat
cssStitches.CSSOverride Default CSS style.-
askeyof JSX.IntrinsicElementsChanges which tag component outputs.ul
AttributeTypeDescriptionDefault
onAction(key: Key) => voidHandler that is called when an item is selected.-
onSelectionChange(keys:SelectionType) => anyHandler that is called when the selection changes.-
AttributeTypeDescriptionDefault
idstringThe element's unique identifier. See MDN-
aria-labelstringDefines a string value that labels the current element-
aria-labelledbystringIdentifies the element (or elements) that labels the current element-
aria-describedbystringIdentifies the element (or elements) that describes the object.-
aria-detailsstringIdentifies the element (or elements) that provide a detailed, extended description for the object.-

AttributeTypeDescriptionDefault
keyKeyThe unique key for the menu item.false
commandbooleanRight-aligned label text content, useful for displaying hotkeys.-
descriptionbooleanDescription text element inside the dropdown menu item.-
iconReactNodeThe icon to render before the dropdown menu item's label.-
withDividerbooleanWhether the dropdown item should have a border on topfalse
dividerWeightNormalWeightThe dropdown item divider heightlight
colorSimpleColorsThe dropdown item colordefault
textColorSimpleColorsThe dropdown item text colordefault
variantDropdownVariantThe dropdown item variantionflat
cssStitches.CSSOverride Default CSS style.-
askeyof JSX.IntrinsicElementsChanges which tag component outputs.li
AttributeTypeDescriptionDefault
aria-labelstringA screen reader only label for the dropdown menu item.-

AttributeTypeDescriptionDefault
headingReactNodeThe heading for the section.-
AttributeTypeDescriptionDefault
aria-labelstringAn accessibility label for the section. Required if heading is not present.-

Trigger Type

type TriggerType = 'menu' | 'listbox';
type MenuTriggerType = 'press' | 'longPress';

Collection Element Type

type CollectionElement<T> = SectionElement<T> | ItemElement<T>;

Collection Children Type

type CollectionChildren<T> =
  | CollectionElement<T>
  | CollectionElement<T>[]
  | ((item: T) => CollectionElement<T>);

Focus Strategy Type

type FocusStrategyType = 'first' | 'last';

Keyboard Delegate Type

import { Key } from 'react';

// Returns the key visually below the given one, or null for none.
getKeyBelow(key: Key): Key
// Returns the key visually above the given one, or null for none.
getKeyAbove(key: Key): Key
// Returns the key visually to the left of the given one, or null for none.
getKeyLeftOf(key: Key): Key
// Returns the key visually to the right of the given one, or null for none.
getKeyRightOf(key: Key): Key
// Returns the key visually one page below the given one, or null for none.
getKeyPageBelow(key: Key): Key
// Returns the key visually one page above the given one, or null for none.
getKeyPageAbove(key: Key): Key
// Returns the first key, or null for none.
getFirstKey(key?: Key, global?: boolean): Key
// Returns the last key, or null for none.
getLastKey(key?: Key, global?: boolean): Key
// Returns the next key after fromKey that matches the given search string, or null for none.
getKeyForSearch(search: string, fromKey?: Key): Key

Selection Mode Type

type SelectionModeType = 'none' | 'single' | 'multiple';

Selection Type

import { Key } from 'react';

type SelectionType = 'all' | Set<Key>;

Simple Colors

type SimpleColors =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error';
type DropdownVariants = 'flat' | 'light' | 'solid' | 'shadow';

Normal Weights

type NormalWeights = 'light' | 'normal' | 'bold' | 'extrabold' | 'black';
gradient blue backgroundgradient violet background