Menu

A menu contains a list of app-like JavaScript actions or functions.

Examples

TODO:
Add updated examples once complete in GitLab UI. Create an issue

View in Pajamas UI Kit →

Structure

TODO:
Add structure visual and element list. Create an issue

Guidelines

While the term "dropdown" generally refers to an element that reveals a related panel, the dropdown menu component is specifically a button with an aria-haspopup="menu" attribute that opens a panel of options with role="menu".

When to use

  • A menu is a particular type of dropdown that should only be used for app-like JavaScript actions or functions, like replicating a desktop application's main menu bar.

When not to use

  • A menu is not for website navigation, use a disclosure widget instead.
  • If the options within the panel are selectable, refer to the listbox component.
  • If a user is selecting a single text option from a group of options within a form, consider using a <select> element, radio group, or checkboxes instead.
  • If you need a way for a user to expand or collapse a content section, use an accordion instead.

Trigger button variants

A button that triggers a dropdown panel comes in a few variants to fit different situations.

  • Dropdown button: A dropdown button has a chevron-down icon to the right of the text label to indicate it will toggle additional content.
  • Split dropdown button: A split dropdown button is a special button group with two segments. The left text button is for the most common option and an attached dropdown button to the right opens a panel with additional options.
  • Icon dropdown: An icon button, like one that uses the vertical or horizontal ellipsis icons, functions similarly to other trigger buttons with the only difference being only an icon label with no text.

Behavior

  • By default, the dropdown panel opens below and is aligned to the left of the trigger button. However, when there isn't enough space in the viewport, the panel uses edge detection to position it above and/or aligned to the right of the trigger.
  • If the content within the dropdown panel exceeds the maximum height then a scrim (gradient overlay) appears at the bottom of the panel as an overflow affordance. When a user has scrolled to the bottom of the overflowed content the scrim is removed.
  • When an action is selected that impacts the current view, the panel is closed and the action performed.
  • When an action option is selected that causes a page refresh or other change of context the panel returns to a closed state.
  • All panels can be closed by clicking outside of them, using the esc key, or by focus moving to an element outside of the component.
  • A limited amount of actions that don't scroll can be fixed at the bottom of a dropdown panel.

Content

  • A header can provide context for the list of actions.
  • Section headers can categorize actions into meaningful groups.
  • Action text should be concise and clearly indicate the action or function it performs.

Accessibility

Reference

Last updated at: