Dropdown | NextUI - Beautiful, fast and modern React UI Library

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

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.

Key	Description
`Space`	When 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.
`Enter`	When 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.
`ArrowDown`	When focus is on `DropdownMenu.Trigger` or `Dropdown.Button`, opens the dropdown menu. When focus is on an item, moves focus to the next item.
`ArrowUp`	When focus is on an item, moves focus to the previous item.
`Esc`	Closes the dropdown menu and moves focus to `DropdownMenu.Trigger` or `Dropdown.Button`.
`A-Z` or `a-z`	When 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

Attribute	Type	Description	Default
children*	`ReactNode[]`	The content of the dropdown. It's usually the `Dropdown.Trigger`, `Dropdown.Button` and `Dropdown.Menu`.	-
type	TriggerType	The type of dropdown menu that the dropdown trigger opens.	`menu`
trigger	MenuTriggerType	How the dropdown menu is triggered.	`press`
closeOnSelect	`boolean`	Whether the dropdown menu closes when a selection is made.	`true`
isDisabled	`boolean`	Whether dropdown trigger is disabled.	`false`
disableTriggerPressedAnimation `new`	`boolean`	Whether the trigger should show a pressed animation when the menu is open.	`false`
PopoverProps	PopoverProps	Since dropdown is based on the `Popover` you can use any of the `Popover` props.	-

Attribute	Type	Description	Default
PopoverEvents	PopoverEvents	Since dropdown is based on the `Popover` you can use any of the `Popover` events.	-

Dropdown.Trigger Props

Attribute	Type	Description	Default
children*	`ReactNode`	The 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.	-

Dropdown.Button Props

Attribute	Type	Description	Default
ButtonProps	ButtonProps	Since dropdown button is based on the `Button` you can use any of the `Button` props.	-

Dropdown.Menu Props

Attribute	Type	Description	Default
children*	CollectionChildrentype	The contents of the collection. It's usually the `Dropdown.Item` or `Dropdown.Section`.	-
items	`Iterable<T>`	Item objects in the collection.	-
selectedKeys	`all` `Iterable<T>`	The currently selected keys in the collection (controlled).	-
defaultSelectedKeys	`all` `Iterable<T>`	The initial selected keys in the collection (uncontrolled).	-
disabledKeys	`Iterable<T>`	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.	-
selectionMode	SelectionModeType	The type of selection that is allowed in the collection.	-
keyboardDelegate	KeyboardDelegateType	An optional keyboard delegate implementation for type to select, to override the default.	-
color	SimpleColors	The dropdown menu items color	`default`
textColor	SimpleColors	The dropdown menu items text color	`default`
variant	DropdownVariant	The dropdown menu items variantion	`flat`
isVirtualized	`boolean`	Whether the dropdown menu uses virtual scrolling.	`false`
disallowEmptySelection	`boolean`	Whether the collection allows empty selection.	`false`
autoFocus	`boolean` FocusStrategyType	Where the focus should be set.	`false`
shouldFocusWrap	`boolean`	Whether keyboard navigation is circular.	`false`
css	`Stitches.CSS`	Override Default CSS style.	-
containerCss `new`	`Stitches.CSS`	Override the dropdown mmenu container (`Popover.Content`) CSS style.	-
as	`keyof JSX.IntrinsicElements`	Changes which tag component outputs.	`ul`

Dropdown.Menu Events

Attribute	Type	Description	Default
onAction	`(key: Key) => void`	Handler that is called when an item is selected.	-
onSelectionChange	`(keys:SelectionType) => any`	Handler that is called when the selection changes.	-

Dropdown.Menu Accessibility Props

Attribute	Type	Description	Default
id	`string`	The element's unique identifier. See MDN	-
aria-label	`string`	Defines a string value that labels the current element	-
aria-labelledby	`string`	Identifies the element (or elements) that labels the current element	-
aria-describedby	`string`	Identifies the element (or elements) that describes the object.	-
aria-details	`string`	Identifies the element (or elements) that provide a detailed, extended description for the object.	-

Dropdown.Item Props

Attribute	Type	Description	Default
key	Key	The unique key for the menu item.	`false`
description	`string`	Description text element inside the dropdown menu item.	-
command	`string`	Right-aligned label text content, useful for displaying hotkeys.	-
icon	`ReactNode`	The icon to render before the dropdown menu item's label.	-
dividerWeight	NormalWeights	The dropdown item divider height	`light`
color	SimpleColors	The dropdown item color	`default`
textColor	SimpleColors	The dropdown item text color	`default`
variant	DropdownVariant	The dropdown item variation	`flat`
withDivider	`boolean`	Whether the dropdown item should have a border on top	`false`
showFullDescription `new`	`boolean`	Whether the item description should be truncated or not.	`false`
css	`Stitches.CSS`	Override Default CSS style.	-
as	`keyof JSX.IntrinsicElements`	Changes which tag component outputs.	`li`

Dropdown.Item Accessibility Props

Attribute	Type	Description	Default
aria-label	`string`	A screen reader only label for the dropdown menu item.	-

Dropdown.Section Props

Attribute	Type	Description	Default
heading	`ReactNode`	The heading for the section.	-

Dropdown.Section Accessibility Props

Attribute	Type	Description	Default
aria-label	`string`	An 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";

Tooltip Progress

Created by Junior Garcia

Deployed on

Documentation