Skip to content

DropdownMenu

Description

DropdownMenu is a component for displaying the menu of options and their nested items.

TIP

Note that the DropdownMenu component doesn't handle the value change in the trigger. This mechanism is implemented in the Select.

Appearance

Sizes

The DropdownMenu has two sizes.

DropdownMenu sizes
SizeAppearance example and indents
M
L

Width

The dropdown width can be defined in two ways.

  1. By the maximum width of the trigger.
  2. By the longest item in the list.

Height

We recommended to avoid limiting the dropdown's height for the menus. It's important for the user to observe all available options, especially if there are links or different controls. We don’t recommend using a scroll for such menus.

Placement

The menu always drops down, regardless of space availability under the trigger. This behavior is necessary to enable accessible keyboard control of the menu.

There are three types of menu items:

  • default (nonselectable, only for launching actions)
  • selectable (menuitemradio role)
  • multiselect (menuitemcheckbox role)

Default menu item states

Default menu item states
StateStyles
Defaultbackground-color: var(--dropdown-menu-item)
Hoverbackground-color: var(--dropdown-menu-item-hover)
Disabledopacity: var(--disabled-opacity)

Selectable menu item states

Selectable menu items (menuitemradio) have the same states as default items, plus an additional selected state:

Selectable menu item states
StateStyles
Selectedbackground-color: var(--dropdown-menu-item-selected)
Selected + hoverbackground-color: var(--dropdown-menu-item-selected-hover)

Multiselect menu item states

Multiselect menu items (menuitemcheckbox) include a checkbox that shows whether the item is selected. The background and border styles are the same for selected and unselected items.

Multiselect menu item states
StateStyles
Defaultbackground-color: var(--dropdown-menu-item)
Hoverbackground-color: var(--dropdown-menu-item-hover)
Selectedbackground-color: var(--dropdown-menu-item)
Disabledopacity: var(--disabled-opacity)

Add item button

This item with a button adds a new item and has the following states:

DropdownMenu addition button states
StateAppearance exampleDescription
Default trigger buttonTrigger has the same styles as a regular item.
Active inputClicking on the button opens an input in the focus state. The list item has no hover state in this case.
Entering valueTo add an item, click the submit icon. To close the input, click outside the input or press the Esc key. If user entered data but closed the input without submitting, their entered value should be saved.
LoadingFor loading state change submit icon to Spin with XS size. Input receives the disabled state.
ErrorIf an error occurred during adding, show the error message in a tooltip and highlight the input.

Grouping menu items

Divider

Menu items can be visually separated by inserting a Divider between them. Divider must have the following margins depending on the size of the menu.

Divider margins
Menu sizeMargins
Mmargin-top: var(--spacing-1x, 4px)
margin-bottom: var(--spacing-1x, 4px)
Lmargin-top: var(--spacing-2x, 8px)
margin-bottom: var(--spacing-2x, 8px)

Titled group

You can group menu items using the DropdownMenu.Group component. Groups always have titles.

Group title is noninteractive, always has font-weight: var(--bold) and the same size as menu items.

You can put the following addons before and after the text inside the list item:

Addon before text

Before the text you can place an icon, flag or image. In this case icon always has the color of the text.

Addon before the text examples
AddonAppearance example
Icon
Flag
Image/avatar

Addon after text

After the text you can place either noninteractive and interactive addons: an icon, badge, switch, link or button.

Button inside the item cases of use
CaseAppearance exampleDescription
Delete itemIf a list item can be deleted, use Button with use="secondary" and tertiary theme.
Drag and dropTo drag and drop list items, use the MoveAlt icon with the --icon-secondary-neutral color. The icon should appear when hovering over the item, and the cursor should change to move. For more information on dragging and dropping items, refer to the Drag and drop.

Info icon

Avoid using icons with tooltips in menu items. Check the Tooltip section.

Counter

You can place a text counter after the text. It should have the same size that item's text has.

Badge

Badge can be placed after the text. The margin between the text and the badge is always 4px. If item with badge is selected, then don’t show badge in the trigger.

badge

Hint

You can display additional information in menu items using the DropdownMenu.Item.Hint component.

Hint text sizes
List sizeAppearance exampleTokens
M--fs-200, --lh-200
L--fs-300, --lh-300

Tooltip

If you want to add a tooltip to an item, apply it to the entire item. We don't recommend adding an additional Info icon, as it doesn't display a tooltip on hover.

Nested menus

The item can have a nested menu. In this case, it should have the ChevronRight icon to indicate the nesting.

The maximum recommended nesting level is two, but it's better to avoid nesting altogether because large menu of options can be inconvenient to work with. If there's sufficient space, nested menus will drop to the right; otherwise, they will drop to the left.

Nested menus hide after the 0.3 seconds delay in the following cases:

  • When user hovers over another item in the parent menu.
  • When mouse cursor moves away from the dropdown.
  • When the entire dropdown closes (for example, by pressing the Esc button).

To prevent inconvenience for users with small screens, avoid expanding the entire chain of submenus when opening a dropdown with a selected item in such a menu.

Released under the MIT License.

Released under the MIT License.