Themenu role is a type of composite widget that offers a list of choices to the user.

Description

Amenu generally represents a grouping of common actions or functions that the user can invoke. Themenu role is appropriate when a list of menu items is presented in a manner similar to a menu on a desktop application. Submenus, also known as pop-up menus, also have the rolemenu.

While the term "menu" is a generically used term to describe site navigation, themenu role is for a list of actions or functions that require complex functionality, such as composite widget focus management and first-character navigation

A menu can be a permanently visible list of controls or a widget that can be made to open and close. A closedmenu widget is usually opened, or made visible, by activating a menu button, choosing an item in a menu that opens a submenu, or by invoking a command, such asShift + F10 in Windows which opens a context specific menu.

When a user activates a choice in a menu that has been opened, the menu usually closes. If the menu choice action invokes a submenu, the menu will remain open and the submenu is displayed.

When a menu opens, keyboard focus is placed on the first menu item. To be keyboard accessible, you need tomanage focus for all descendants: all menu items within themenu are focusable. The menu button which opens the menu and the menu items, rather than the menu itself, are the focusable elements.

Menu items includemenuitem,menuitemcheckbox, andmenuitemradio.Disabled menu items are focusable but cannot be activated.

Menu items can be grouped in elements with thegroup role, and separated by elements with roleseparator. Neithergroup norseparator receive focus or are interactive.

If amenu is opened as a result of a context action,Escape orEnter may return focus to the invoking context. If focus was on the menu button,Enter opens the menu, giving focus to the first menu item. If focus is on the menu itself,Escape closes the menu and returns focus to the menu button or parent menubar item (or the context action that opened the menu).

Elements with the rolemenu have an implicitaria-orientation value ofvertical. For horizontally oriented menu, usearia-orientation="horizontal".

If the menu is visually persistent, consider themenubar role instead.

Associated WAI-ARIA roles, states, and properties

menuitem,menuitemcheckbox, andmenuitemradio roles

Roles of items contained in a containingmenu ormenubar, known collectively as "menu items". These must be able to receive focus.

group role

Menu items can be nested in agroup

separator role

A divider that separates and distinguishes sections of content or groups of menu items within the menu

tabindex attribute

Themenu container hastabindex set to-1 or0 and each item in the menu hastabindex set to-1.

aria-activedescendant

Set to the ID of the focused item, if there is one.

aria-orientation

indicates whether the menu orientation is horizontal or vertical; defaults tovertical if omitted.

aria-label oraria-labelledby

Themenu is required to have an accessible name. Usearia-labelledby if a visible label is present, otherwise usearia-label. Either include thearia-labelledby set to a theid to themenuitem orbutton that controls its display or usearia-label to define the label.

aria-owns

Only set on the menu container to include elements that are not DOM children of the container. If set, those elements will appear in the reading order in the sequence they are referenced and after any items that are DOM children. When managing focus, ensure the visual focus order matches this assistive technology reading order.

Keyboard interactions

Space /Enter

If the item is a parent menu item, it opens the submenu and moves focus to the first item in the submenu. Otherwise, activates the menu item, which loads new content and places focus on the heading that titles the content.

Escape

When in a submenu, it closes the submenu and moves focus to the parent menu or menubar item.

Right Arrow

In a menubar, moves focus to the next item in the menubar. If focus is on the last item, it moves focus to the first item. If in a submenu, if focus is on an item that does not have a submenu, it closes the submenu and moves focus to the next item in the menubar. Otherwise, it opens the submenu of the newly focused menubar item, keeping focus on that parent menubar item. If not in a menubar or submenu and not on amenuitem with a submenu, if focus is not the last focusable element in the menu, it optionally moves focus to the next focusable element.

Left Arrow

Moves focus to the previous item in the menubar. If focus is on the first item, it moves focus to the last item. If in a submenu, it closes the submenu and moves focus to the parent menu item. If not in a menubar or submenu, if focus is not the first focusable element in the menu, it optionally moves focus to the last focusable element.

Down Arrow

Opens submenu and moves focus to the first item in the submenu.

Up Arrow

Opens submenu and moves focus to the last item in the submenu.

Home

Moves focus to the first item in the menubar.

End

Moves focus to the last item in the menubar.

Any character key

Moves focus to the next item in the menubar having a name that starts with the typed character. If none of the items have a name starting with the typed character, focus does not move.

Examples

Below are two example menu implementations.

Example 1: navigation menu

<div>  <button aria-haspopup="true" aria-controls="menu">    <img src="hamburger.svg" alt="Page Sections" />  </button>  <ul role="menu" aria-labelledby="menubutton">    <li role="presentation">      <a role="menuitem" href="#description">Description</a>    </li>    <li role="presentation">      <a        role="menuitem"        href="#associated_wai-aria_roles_states_and_properties">        Associated WAI-ARIA roles, states, and properties      </a>    </li>    <li role="presentation">      <a role="menuitem" href="#keyboard_interactions">        Keyboard interactions      </a>    </li>    <li role="presentation">      <a role="menuitem" href="#examples">Examples</a>    </li>    <li role="presentation">      <a role="menuitem" href="#specifications">Specifications</a>    </li>    <li role="presentation">      <a role="menuitem" href="#see_also">See Also</a>    </li>  </ul></div>

To progressively enhance this navigation widget that is by default accessible, the class to hide themenu and the inclusion oftabindex="-1" on the interactive menuitem content should be added with JavaScript on load.

When including a "menu" for site navigation, do not use themenu role. Rather, for the main site navigation use the native HTML<nav> element or simply a list of links. Themenu role should be reserved for composite widgets requiring focus management. SeeARIA practices for disclosure navigation for an explanation and additional examples.

Example 2: menubar submenu option picker

The following snippet of code is a popup menu nested in a menubar. It is displayed when the menu button is activated. It is a menu to select the text color from a list of color options:

<div>  <button    type="button"    aria-haspopup="menu"    aria-controls="colormenu"    tabindex="0"    aria-label="Text Color: purple">    Purple  </button>  <ul role="menu" aria-label="Color Options" tabindex="-1">    <li      role="menuitemradio"      aria-checked="true"           tabindex="-1">      Purple    </li>    <li      role="menuitemradio"      aria-checked="false"           tabindex="-1">      Magenta    </li>    <li      role="menuitemradio"      aria-checked="false"           tabindex="-1">      Black    </li>  </ul></div>

The button that opens the menu hasaria-haspopup="menu" set, explicitly indicating that the popup it controls is amenu.

For a menu to open, the user generally interacts with a menu button as the opener. The menu button must be focusable and respond to both click and keyboard events. When focused, selectingEnter,Space,Down Arrow, or theUp Arrow should open the menu and place focus on a menu item.

The opening and closing of the menu toggles thearia-expanded="true" attribute on the button. It is added when the menu is open. Removed or set tofalse when the menu is closed. Thetrue value indicates that the menu is displayed and that activating the menu button closes the menu.

When the menu is open, the button itself generally does not receive focus as users arrow through the menu items. Rather,Escape and optionallyShift + Tab closes the menu and returns focus to the menu button.

Themenu role was set on the<ul>, identifying the<ul> element as a menu.

The showing and hiding of the menu can be done with CSS. For example, in these code examples we can use the attribute and next-sibling selectors to toggle the visibility of the menu:

[role="menu"] {  display: none;}[aria-expanded="true"] + [role="menu"] {  display: block;}

The navigation example has a static button. The submenu example has a button that gets updated when the user selects a new value. In this case, thearia-label="Text Color: purple" is set on themenu element. It defines the accessible name for the menu as "Text color: purple"; identifying the purpose of the menu (selecting a text color) and the current value (purple). When a new color is selected, the value of thearia-label property should be updated as well.

Specifications

See also

• menubar
• menuitem
• menuitemcheckbox
• menuitemradio
• aria-haspopup