DropdownMenu
Github
StorybookA set of actions in a popover.
Anatomy
- Menu: Wrapper than houses menu items. Positioned relative to the trigger.
- Menu item: Single action or link within the menu. May include an icon, description, or tooltip for added context.
Guidelines
When to use
DropdownMenus display a list of actions or links as menu items in a floating overlay when its trigger is activated. DropdownMenus are best used to cleanly group actions together within a specific context, such as row-level actions inside a table or account settings.
DropdownMenu vs Select and Popover
DropdownMenus, Selects, and Popovers similarly offer a floating overlay of content for the user to choose or interact with. It's important to be mindful about the differences as they are not interchangeable:
- DropdownMenus trigger actions or navigation. Selecting an item performs an operation (e.g. delete, edit, navigate) and closes the menu.
- Selects are form controls for choosing values. The selected option persists as the field's value and is submitted with the form.
- Popovers display freeform content such as text, forms, or other UI elements that are too complex for a Tooltip.
Best practices
Icons
Icons provide nice, helpful visual treatments to menu items. Be consistent about icon usage, especially within groups. If one menu item includes an icon, add icons for the remaining items so visual alignment is consistent.
Menu length
Shorter menus make for a more focused user experience. If the DropdownMenu's list grows to more than 7-10 items, consider grouping them if possible to reduce cognitive load.
Nesting
Limit nested menu items to one sub-level. Deeply nested menus are difficult to navigate with both mouse and keyboard, and may potentially obscure both available actions and surrounding content. Consider revising the menu structure or using labels to categorize items.
Appearance
Footer
The footer is displayed after all items and is used for additional information or hints relating to the entire list.
A footer anchored below the menu items provides supplemental list context.
Groups
Group related items into visually distinct sections separated by a divider. A group may include a label that displays above the items it categorizes. Unlabeled groups are only denoted by the divider.
Use groups wisely. Groups help organize longer lists. For shorter lists, group actions together if the user experience or visual hierarchy is improved.
Group headers categorize items and help users scan the menu quickly.
Groups without a label render a divider to visually separate sections.
Item variations
DropdownMenu items support several configurations to visually aid users in selecting the most appropriate item.
Icons help users quickly identify actions they may take.
A description provides additional information about the item.
Danger styling warns users that an action is destructive or irreversible.
Trigger styles
The DropdownMenu supports multiple trigger styles depending on the context.
The base trigger renders as inline text that inherits surrounding text styles.
Icon-only buttons are commonly used in tighter components or layouts such tables or toolbars.
Standard Pluma Buttons may be used as the trigger.
Custom triggers can be created with any interactive to fulfill different use cases.
Behaviors
States
The menu item's rest state uses base styling.
A menu item's background color changes on mouse hover.
Keyboard focus applies the same background highlight as hover.
Disabled items are visually dimmed and cannot be interacted with.
Danger items receive the critical color styling to denote destructive actions.
Checkbox items
Checkbox items allow users to toggle options within the menu. They display a check indicator when selected and are ideal for multi-select use cases such as toggling column visibility or enabling filters.
Checkbox items display a check icon to indicate it's selected.
Dismissal
DropdownMenus close when the user clicks an item, clicks outside the menu, or presses the Escape key. Focus returns to the trigger after the menu closes.
Individual items can be configured to keep the menu open when clicked. This is useful when multiple items may need to be selectable or toggled before the menu is dismissed.
Items can be manually set to keep the menu open even when clicked.
Nested menus
DropdownMenu items can be nested within a parent item to organize hierarchical actions or options. Nested items are denoted with a trailing icon. Hovering the parent with the mouse or activating it with a keyboard will reveal the nested menu.
Trailing chevron icons indicate an item has a nested menu that is revealed on hover or keyboard activation.
Placement
The menu content is positioned relative to the trigger. The default placement is bottom-start, which aligns the menu's left edge with the trigger and opens downward. Use other placements to adapt to layout constraints or reading direction.
Be mindful that placement is a preference, not a guarantee. The menu will adjust to the layout accordingly to ensure it's visible within the viewport when possible. When outside of the viewport, the menu will disappear.
The menu opens below the trigger, aligned to its leading edge. This is default.
The menu opens below the trigger, aligned to its trailing edge. Suitable for triggers positioned near the right edge of a container.
The menu opens above the trigger. Used when the trigger is near the bottom of the viewport or when content below may be obscured.
The menu opens to the right of the trigger. Suitable for sidebar or navigational contexts.
Tooltips
Tooltips are another avenue to provide additional context to specific items within the menu. Tooltips may be particularly helpful to explain to users why an item may be disabled.
Tooltips explain why an action is unavailable, helping users understand what would make it available.
Content
Descriptions
Descriptions provide helpful context to the items they describe, such as what action the item performs or when to use it. They're best written as a single, simple sentence.
Group labels
Group labels are single nouns written in uppercase that best describes the category of items it's associated with. Keep labels as brief as possible.
Menu item labels
Use short, specific verb phrases that describe what happens when the item is selected. Sentence case is preferred.
Tooltip text
When using tooltips on disabled items, explain the reason the item is unavailable and, when possible, what the user can do to enable it.