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.
Size | Appearance example and indents |
---|---|
M | ![]() |
L | ![]() |
Width
The dropdown width can be defined in two ways.
- By the maximum width of the trigger.
- 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.
Menu item types and states
There are three types of menu items:
- default (nonselectable, only for launching actions)
- selectable (
menuitemradio
role) - multiselect (
menuitemcheckbox
role)
Default menu item states
State | Styles |
---|---|
Default | background-color: var(--dropdown-menu-item) |
Hover | background-color: var(--dropdown-menu-item-hover) |
Disabled | opacity: var(--disabled-opacity) |
Selectable menu item states
Selectable menu items (menuitemradio
) have the same states as default items, plus an additional selected
state:
State | Styles |
---|---|
Selected | background-color: var(--dropdown-menu-item-selected) |
Selected + hover | background-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.
State | Styles |
---|---|
Default | background-color: var(--dropdown-menu-item) |
Hover | background-color: var(--dropdown-menu-item-hover) |
Selected | background-color: var(--dropdown-menu-item) |
Disabled | opacity: var(--disabled-opacity) |
Add item button
This item with a button adds a new item and has the following states:
State | Appearance example | Description |
---|---|---|
Default trigger button | Trigger has the same styles as a regular item. | |
Active input | Clicking on the button opens an input in the focus state. The list item has no hover state in this case. | |
Entering value | To 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. | |
Loading | For loading state change submit icon to Spin with XS size. Input receives the disabled state. | |
Error | ![]() | If 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.
Menu size | Margins |
---|---|
M | margin-top: var(--spacing-1x, 4px) margin-bottom: var(--spacing-1x, 4px) |
L | margin-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.
Menu item content
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 | Appearance 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.
Case | Appearance example | Description |
---|---|---|
Delete item | ![]() | If a list item can be deleted, use Button with use="secondary" and tertiary theme. |
Drag and drop | ![]() | To 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.
Hint
You can display additional information in menu items using the DropdownMenu.Item.Hint
component.
List size | Appearance example | Tokens |
---|---|---|
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.
Last updated: