Action menu

Action menu is composed of action list and overlay patterns used for quick actions and selections.

Submenus are only available in the React implementation.

Usage

An action menu comprises a set of action list items, where each item represents an action, command, submenu, or the current selection that can be either a single or multi-select. The action menu can be invoked by clicking on a button, icon button, or right-clicking on the list items.

Three instances of action menus. The initial one comprises an icon button that provides two actions. The second one displays a button labeled View:Table and presents three choices (Table, Board, and Roadmap), with Table being the currently selected option. Finally, the third menu is a context menu that appears on right-click and contains a diverse set of options, including single select, submenus, and actions.

The action menu is an extremely versatile component that is not restricted to a single type of action list items at a time. It can be used to create a combination of single select, multi-select, commands, and submenus.

By using dividers and section titles, a hierarchy can be established within the action menu, making it easier to navigate and understand. This allows users to quickly find and access the actions they need, while also providing a clear and organized structure to the menu.

Five examples of how an action menu can be utilized, which includes a context menu, multi-select, single-select, actions, and a combination of multi-select and single-select.

As the action menu is a highly adaptable component, it's crucial to keep the interactions with individual items limited. The following interactions are recommended:

  • enter, click, or tap: These actions trigger an action or navigate into a submenu, based on the selected item.
  • arrow left, arrow up, arrow down, arrow right: These actions can be used to navigate the menu, allowing the user to move between items and submenus with ease.

Menus are a commonly used feature across multiple platforms, and both Apple and Microsoft have detailed documentation on their menus. To create a pleasant user experience, it's important to follow their expected behavior closely.

Anatomy

Action menu opened with an internal `Settings` label. Several elements are emphasized, such as the trigger, actions, overlay menu, trailing visual shortcuts, trailing visual submenu indicator, and the 3 dot dialog indicator.

Content

Open

Action menus can be opened through a button, icon button or by right clicking list items that have a custom context menu associated with them.

Do

Use a button to open a menu.

Don’t

Don’t use a link to open a menu.

When using a button the menu can be opened by clicking or tapping it. When it's focused it can also be opened by hitting return, space or any arrow key.

Open by clicking the trigger button with a mouse

Open by focusing the trigger button and hitting return, space, or any arrow key

Close

The menu will close when pressing the esc or tab key or when pressing enter when a item is focused. Additionally clicking outside the menu item or clicking on a item will close the menu as well.

Close the menu by clicking on an item, clicking on the trigger, or clicking anywhere outside the menu.

Close the menu by hitting enter on an item, esc or tab.

Single and multi select

Single select menu closes upon selection and may update the button label.

Multi select menu closes upon selection and can be re-opened to select more options.

Avoid input controls

The focus should always remain on menu items, and therefore the menu shouldn't include additional form elements like button, input, or checkbox.

Do

Use action menu for quick actions.

Don’t

Don't add form controls like a filterable input, use select panel instead.

While single and multi selection is offered within a menu, the underlying semantics are not true form elements.

Do

Use a checkmark icon for selections.

Don’t

Don't use form elements within a menu.

Alignment

Consistent alignment of icons, titles, and trailing visuals is critical to ensure that the menu is easily scannable. This is especially important when combining single or multi-select items with non-select items.

Do

When a menu includes a single select or multi select then all the items in the menu should be indented.

Don’t

Don't create invidiual alignments when your menu contains a single or multi select.

Icons

When designing menus, it is crucial to adhere to the meaning of the icons used. If any item in the menu does not have a corresponding icon, then all items in that menu should be presented without icons.

Do

When one of the items doesn't have an icon then remove icons altogether.

Don’t

Don't mix items with or without icons as this makes it harder to read.

Especially when providing single or multi select items that rely on a crossmark icon should be avoided as they could be confused with the item's checkmark.

Do

Avoid the usage of icons if the icon conflicts with the selected states checkmark.

Don’t

Don't use crossmark icons for single or multi select items.

Dividers

To enhance the readability of menus that contain numerous item descriptions, it is recommended to incorporate dividers. This can effectively prevent the menu from becoming overwhelming.

Do

Introduce dividers for items with heavy descriptions to improve readability.

Don’t

Don't forget to add dividers when the menu content starts to look heavy.

Trailing visuals

Avoid using trailing visuals to add additional interactions, which reserves them for submenu indicators or keyboard shortcuts.

Do

Create a new section for additional functionality.

Don’t

Don't store additional toggleable functionality in trailing visuals.

Multi-level

A menu with multiple levels is a common UI component used in desktop and mobile applications. It allows users to access nested subitems without cluttering the screen.

Action menu opened with a label for the trigger (button), overlay (menu), and the internal action list.

It's important to understand that menus can't include additional form elements like inputs. That means if you want to provide a input that filters the subitems that you can't rely on this component. Alternatively, you can use a select panel or open a dialog instead of a submenu.

Do

If you want to present filterable data open a dialog instead of a submenu.

Don’t

Don't use form elements inside a menu.

Since you can't include form elements within a menu that also means that you can't combine a select panel with a action menu.

Do

If you want to present filterable data do this through a dialog.

Don’t

Don't mix select panels with action menus.

When using submenus, don't use the trailing visual to communicate selected values within its submenu. Leave this space for submenu indicators.

Do

Use trailing visuals for submenu indicators or keyboard shortcuts.

Don’t

Don't use trailing visual to communicate selected items in submenus.

On smaller viewports, the menu should always be re-positioned to fit within the viewport. This could mean that a submenu overlaps it's parent menu.

Do

Reposition menus to stay within the viewport, especially on narrow viewports.

Don’t

Don't position menus off screen, especially on narrow viewports.

Options

Trigger

Menus can be triggered through a button, icon button or right clicking list items. For simple select menus that display the selection in a button, a label must be persist either internally or externally.

Items

Here is an overview of action list items that are compatible with menus:

  • Action: Triggers an action or dialog. Trailing visuals can be used for keyboard shortcuts.
  • Single/multi select: Represented by a check and never a HTML checkbox. Trailing visuals can be used for keyboard shortcuts.
  • Submenu: Represented by a chevron-right as a trailing visual.
  • Section header: To add clarification to a section.
  • Divider: To create sections for your selections, actions or submenus.

Inactive items

Three examples: 1. An action menu that works just fine; 2. An action menu with some items disabled; 3. An action menu with all items disabled

If items in a menu have been affected by a system error such as an outage, they may be put into an inactive state with a message in each item explaining why it's disabled.

If an action menu contains menu items that are very closely related (for example: the action menu for adding a file to a repo) and we can detect that none of the menu items are available, then put the button that triggers the action menu into an inactive state.

Inactive action menu items follow the same patterns as inactive action list items except:

  • The message explaining why it's unavailable is renderd in the item, not a tooltip. Action menu items don't hide the message in a tooltip because the menu is already hidden until the user opens it.
    • Hiding the message in a tooltip would require the user to do another interaction, and the UI could feel chaotic with so many layers.
  • No alert icon leading visual is necessary since it would be redundant with the error message

Accessibility and usability expectations

When an ActionMenu is opened, focus moves to the first item in the menu.

Users can move between the different menu items – and, if present, submenus – using cursor keys.

If a keyboard user navigates away from an open ActionMenu using Tab / Shift+Tab, the ActionMenu is closed.

An open ActionMenu can be closed using Esc.

Menu items must have a clear and descriptive label. The label is the visible content of the button and will usually be text. The label should be concise and descriptive of the action that will be performed when the menu item is activated.

When using Octicons for leading and trailing visuals on individual menu items, note that icons don't have any text alternative. They are purely visual, and not conveyed to screen readers. Don't rely on these icons alone to convey meaning – make sure that the text label of the menu item provides sufficient meaning/context on its own.

Every menu item must have a minimum target size of 24×24 CSS pixels. This is to ensure that the button is large enough to be easily activated by users with motor impairments.

The currently focused menu item can be activated using Space or Enter. When a menu item is activated, the ActionMenu is closed, and the relevant functionality is executed. In the case of selectable menu items, the focused item is checked/unchecked, and the ActionMenu is closed.

When the ActionMenu is closed, focus returns to the most logical location in the page – in general, this is the trigger control that originally opened the ActionMenu.

See focus management for more information.

When a menu is open, hitting a letter key for the first letter in an item to be selected will move focus to that item. If two items have the same first letter, the first item in the list will be focused first, and hitting the letter key again will focus the next item.

Inactive menu items vs disabled menu items

Inactive menu items are still focusable and may execute actions, so they should not be marked as disabled using aria-disabled. For example, they might trigger a modal with information about an outage, which is still a valid action.

This behavior is consistent with the behavior of inactive buttons. See the button component accessibility guidelines and inactive button guidelines for more details.

Inactive menu items:

  • Can be activated
  • Need to be able to get focus so screen reader users can "read" the message about it being inactive

Disabled menu items:

  • Do not get focus
  • Cannot be activated

Built-in accessibility features

The component handles all aspects of focus management and keyboard interaction.

The role ("menu") and structure of the ActionMenu are correctly conveyed to screen readers – including the state of selectable menu items, and the correct association of grouped items with their group title/label.

Menu items meet the minimum target size requirement, 24px × 24px.

Keyboard navigation

Trigger button

KeyAction
EnterOpens the menu.
SpaceOpens the menu.
ArrowDownOpens the menu.
ArrowUpOpens the menu.
ArrowLeftOpens the menu.
ArrowRightOpens the menu.
KeyAction
ArrowUpCycle through items starting with current item to previous item
ArrowDownCycle through items starting with current item to next item
ArrowLeftCloses submenu and sets focus back to the parent item
ArrowRightOpens a submenu
EnterTriggers the focused item
SpaceTriggers the focused item
HomeMove focus to first item
PageUpMove focus to first item
EndMove focus to last item
PageDownMove focus to last item
EscClose menu

Implementation requirements

The ActionMenu allows the use of inactive controls – controls that can still be focused, and even activated (for instance, to trigger an informative modal dialog informing the user why a particular item is marked as inactive). Currently, this state of a menu item is not conveyed programmatically, meaning that screen readers won't announce that an item is inactive. Make sure to include descriptive inactiveText to an inactive menu item, to clearly explain the status of the item to all users – and in particular, screen reader users, who won't otherwise be informed of the fact that an item is inactive.

How to test the component

Integration tests

  • The menu items have sufficiently descriptive labels
  • If menu items include icons for their leading or trailing visuals, the purpose of the items is clear even without the icons (as these are only decorative and are not conveyed to screen reader users)
  • When using an inactive menu item, provide a descriptive inactiveText that explains why the item is inactive

Component tests

  • The component exposes an appropriate set of role, aria-* attributes, and overall structure in its rendered output:
    • the component itself has a role="menu"
    • each item within the menu has a role="menuitem", role="menuitemcheckbox, or role="menuitemradio
    • when items are grouped into sections, each section is identified using a container with role="group, and the group has an accessible name (either using aria-label or referencing an existing element with aria-labelledby) that matches the visible section label
    • selectable items have an aria-checked attribute, and correctly reflect their state (aria-checked="true" when checked, aria-checked="false" when not checked)
  • When a menu is opened, focus moves to the first menu item
  • The correct keyboard interactions have been implemented
  • The menu can be closed using Esc
  • When moving keyboard focus away from the menu (using Tab / Shift+Tab) the menu is closed
  • When a menu item is selected, the menu is closed
  • When the menu is closed, focus is programmatically moved back to the most appropriate element in the page – in general, the trigger element that opened the menu; this does not apply when the menu was closed as a result of a keyboard user explicitly navigating away from the menu (using Tab / Shift+Tab)
  • When a menu item is disabled, the item has aria-disabled="true", but still receives focus
  • When a menu item is inactive, the item still receives focus

Refer to the W3C ARIA Authoring Practices Guide for menu button and actions menu button.

Known accessibility issues (GitHub staff only)

View open accessibility issues related to this component