ARIA: menu role
The menu
role is a type of composite widget that offers a list of choices to the user.
Description
A menu
generally represents a grouping of common actions or functions that the user can invoke. The menu
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 role menu
.
While the term "menu" is generically used a term used to describe site navigation, the menu
role is for a list of action 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 closed menu
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 as Shift + 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 to manage focus for all descendants: all menu items within the menu
are focusable. The menu button which opens the menu and the menu items, rather than the menu itself, are the focusable elements.
Menu items include menuitem
, menuitemcheckbox
, and menuitemradio
. Disabled menu items are focusable but cannot be activated.
Menu items can be grouped in elements with the group
role, and separated by elements with role separator
. Neither group
nor separator
receive focus or are interactive.
If a menu
is opened as a result of a context action, Escape or Enter 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 role menu
have an implicit aria-orientation
value of vertical
. For horizontally oriented menu, use aria-orientation="horizontal"
.
If the menu is visually persistent, consider the menubar
role instead.
Associated WAI-ARIA roles, states, and properties
-
Roles of items contained in a containing
menu
ormenubar
, known collectively as "menu items". These must be able to receive focus. group
role-
Menu items can be nested in a
group
separator
role-
A divider that separates and distinguishes sections of content or groups of menu items within the menu
tabindex
attribute-
The
menu
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 to
vertical
if omitted. aria-label
oraria-labelledby
-
The
menu
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, opens submenu and moves focus to 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, closes the submenu and moves focus to 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, moves focus to the first item. If in a submenu, if focus is on an item that does not have a submenu, closes the submenu and moves focus to next item in the menubar. Otherwise, opens submenu of newly focused menubar item, keeping focus on that parent menubar item. If not in a menubar or submenu and not on a menuitem with a submenu, if focus is not the last focusable element in the menu, 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, moves focus to the last item. If in a submenu, closes submenu and moves focus to parent menu item. If not in a menubar or submenu, if focus is not the first focusable element in the menu, optionally moves focus to the last focusable element.
- Down Arrow
-
Opens submenu and moves focus to first item in the submenu.
- Up Arrow
-
Opens submenu and moves focus to last item in the submenu.
- Home
-
Moves focus to first item in the menubar.
- End
-
Moves focus to last item in the menubar.
- Any character key
-
Moves focus to 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
html
<div>
<button id="menubutton" aria-haspopup="true" aria-controls="menu">
<img src="hamburger.svg" alt="Page Sections" />
</button>
<ul id="menu" 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 the menu
and the inclusion of tabindex="-1"
on the interactive menuitem content should be added with JavaScript on load.
When including a "menu" for site navigation, do not use the menu
role. Rather, for the main site navigation use the native HTML <nav>
element or simply a list of links. The menu
role should be reserved for composite widgets requiring focus management. See ARIA 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:
html
<div>
<button
type="button"
aria-haspopup="menu"
aria-controls="colormenu"
tabindex="0"
aria-label="Text Color: purple">
Purple
<span></span>
</button>
<ul role="menu" id="colormenu" aria-label="Color Options" tabindex="-1">
<li
role="menuitemradio"
aria-checked="true"
style="color: purple"
tabindex="-1">
Purple
</li>
<li
role="menuitemradio"
aria-checked="false"
style="color: magenta"
tabindex="-1">
Magenta
</li>
<li
role="menuitemradio"
aria-checked="false"
style="color: black;"
tabindex="-1">
Black
</li>
</ul>
</div>
The button that opens the menu has aria-haspopup="menu"
set, explicitly indicating that the popup it controls is a menu
.
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, selecting Enter, Space, Down Arrow, or the Up Arrow should open the menu and place focus on a menu item.
The opening and closing of the menu toggles the aria-expanded="true"
attribute on the button. It is added when the menu is open. Removed or set to false
when the menu is closed. The true
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 received focus as users arrow thru the menuitems. Rather, Escape and optionally Shift + Tab closes the menu and returns focus to the menu button.
The menu
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 adjacent sibling selectors to toggle the visibility of the menu:
css
[role="menu"] {
display: none;
}
[aria-expanded="true"] + [role="menu"] {
display: block;
}
The navigation example has a static button. In submenu example has a button that gets updated when the user selects a new value. In this case, the aria-label="Text Color: purple"
is set on the menu
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 selection to a new color is made, the value of the aria-label
property should be updated as well.
Specifications
Specification |
---|
Accessible Rich Internet Applications (WAI-ARIA) # menu |
ARIA Authoring Practices # menu |