Menu

Reported as: No group members with required role

A menu or menubar must contain items with a menu item role.

When the container's children have no menu item role, such as <button> elements left with their native role, assistive technology reports a menu with nothing in it. Screen reader users can't move through or activate its items the way the menu promises.

Give each item role="menuitem", menuitemcheckbox, or menuitemradio, and place it directly in the menu or inside a group in the menu.

Severity: Serious

Reported as: Element has incorrect role

Each part of a menu must expose its role: menu or menubar on the container, and menuitem, menuitemcheckbox, or menuitemradio on each item.

When an item keeps its native role, such as a <button> without role="menuitem", or the container has no role, assistive technology presents a set of buttons or plain content rather than a menu. Users aren't told they can move through it with the arrow keys, and checkable items don't report their state.

Set role="menu" or role="menubar" on the container, and the matching menu item role on each item.

Severity: Critical

Reported as: Incorrect root element

A menu item role should sit on the element that users focus and activate.

When the role is on a wrapper, such as an <li role="menuitem"> around a focusable <button>, focus lands on an element that assistive technology reports as a plain button. The menu item itself never receives focus, so what users hear doesn't match the menu's structure.

Put the role, the accessible name, and the focus handling on the same element, and give any wrapper role="none".

Reported as: Accessible name

A menu item must have an accessible name that says what it does.

When an item has no name, as happens with an icon-only item, screen reader users hear only "menu item," and voice control users have nothing to say to activate it. Nobody using either can tell what the item does without running it.

Give each item visible text. When an item shows only an icon, add aria-label to the item and hide the icon with aria-hidden="true".

Severity: Critical

Reported as: Group members missing accessible names

Every item in a menu or menubar must have an accessible name.

When some items in a menu have no name, screen reader users moving through it hear "menu item" at those positions with nothing to tell the items apart. Voice control users can't activate them by name.

Give every item visible text, or an aria-label when it shows only an icon.

Severity: Critical

Reported as: Group contains duplicate names

Items in the same menu should each have a different accessible name.

When two items share a name, such as two "Edit" items for different targets, screen reader users can't tell which does what, and voice control users can't choose between them.

Make each name distinct, for example "Edit document" and "Edit template." When only the context differs, fold that context into the name rather than relying on the item's position.

Severity: Serious

Reported as: Missing contextual labeling

A menu or menubar must have an accessible name that identifies it.

When a menu has no name, assistive technology reports only that the user has entered a menu. Screen reader users aren't told which one, and on a page with several menus they can't tell them apart or decide whether to enter one without going through its items.

Give a popup menu aria-labelledby that points to the control that opens it. Point a menubar's aria-labelledby at its visible label, or use aria-label when there's no visible text. Name the menu for what it holds rather than with the word "menu."

Severity: Serious

Reported as: Menu button has no aria-haspopup attribute

A parent menu item should carry aria-haspopup to declare its submenu.

When the attribute is missing, screen reader users aren't told that the item opens a submenu. They may activate it expecting a command, or not look for the options it holds.

Add aria-haspopup="menu" to each menu item that opens a submenu.

Severity: Moderate

Reported as: Invalid aria-haspopup value

A parent menu item's aria-haspopup value should name the kind of popup it opens.

When the value names a different kind of popup, such as "dialog" or "listbox" on an item that opens a submenu, or isn't a value ARIA defines, assistive technology describes the wrong popup or none. Users can't anticipate what opening the item will do.

Set aria-haspopup to "menu" or "true", and give the submenu it opens role="menu".

Severity: Minor

Reported as: Conflicting aria-orientation

A menu's aria-orientation value must match the arrow keys that move focus through it.

When the declared orientation and the keys disagree, such as a menubar laid out as a column that keeps its implicit horizontal orientation while Up Arrow and Down Arrow move focus, screen readers tell users to press keys that don't work.

Set aria-orientation="vertical" on a vertical menubar or "horizontal" on a horizontal menu, and leave it out when the layout matches the role's default.

Severity: Serious

Reported as: Invalid aria-orientation value

A menu's aria-orientation should be "horizontal" or "vertical".

When the attribute holds any other value, such as a misspelling, assistive technology ignores it and uses the role's default. When that default doesn't match the layout, screen readers tell users to press keys that don't work.

Use one of the two values, or remove the attribute when the role's default is correct.

Severity: Minor

Reported as: Conflicting aria-expanded value

A parent menu item's aria-expanded value must match whether its submenu is visible.

When the value contradicts the screen, such as "false" while the submenu is displayed, screen reader users are told the opposite of what sighted users see. They may try to open a submenu that's already open, or not know that one is showing.

Set aria-expanded="true" whenever the submenu is shown and "false" whenever it's hidden, in the same function that shows and hides it.

Severity: Critical

Reported as: Aria-expanded value did not change

A parent menu item's aria-expanded value must change every time its submenu opens or closes.

When the value is set once and never updated, it's right in only one state. Screen reader users hear the same state whether the submenu is open or closed, and get no confirmation that their action opened it.

Update aria-expanded each time the submenu opens or closes, whether a key press, a click, or a script opens or closes it.

Severity: Serious

Reported as: Missing aria-expanded attribute

A parent menu item must carry an aria-expanded attribute.

When the attribute is missing, assistive technology can't report whether the submenu is open, so screen reader users don't know whether the options they're looking for are available.

Add aria-expanded="false" to every parent menu item, and change it to "true" while its submenu is shown. Leave it off items that run a command.

Severity: Serious

Reported as: Component does not support disabled state

In a menu, only the menu or menubar, its groups, and its menu items, including items that open submenus, can declare a disabled state.

When disabled or aria-disabled sits on a separator, on a wrapper around an item, or on an icon inside one, assistive technology may drop the state or report it on something users can't operate, while the item itself is still reported as available.

Move the state onto each menu item that isn't available, or onto the menu or menubar when none of its items is.

Severity: Serious

Reported as: Element type does not support disabled state

An element in a menu must carry disabled or aria-disabled only when its role supports a disabled state.

When the state sits on an element whose role has none, such as a wrapper, a list item or a heading, assistive technology may drop it or report it on something users can't operate, while the control that really is unavailable is still reported as available.

Remove the attribute from that element, and set the disabled state on the control itself, using an element or role that supports it, such as a native <button>.

Severity: Serious

Reported as: Conflicting disabled values

A menu item must declare its disabled state in one way, with one value.

When an item carries both disabled and aria-disabled with values that disagree, such as disabled with aria-disabled="false", assistive technology can report a state different from the one the browser enforces. Users can't tell whether the item will run.

Use aria-disabled alone on menu items, and remove it or set it to "false" when the item becomes available.

Severity: Serious

Reported as: Element does not support the disabled attribute

A menu item must convey its disabled state with aria-disabled.

When a <div> or <li> used as a menu item carries the disabled attribute, the browser ignores it. Assistive technology reports the item as available, so screen reader users aren't told it's unavailable, and it still runs when anyone activates it.

Set aria-disabled="true" on the item, and have script ignore Enter, Space, and clicks on it until it's available again.

Severity: Serious

Reported as: Disabled menu item not discoverable

A disabled menu item must stay reachable with the arrow keys.

When arrow-key navigation skips disabled items, keyboard and screen reader users never learn those commands exist. They can't tell that an option is unavailable for now rather than missing.

Keep disabled items in the arrow-key sequence, and let aria-disabled="true" report their state. Ignore attempts to run them instead of removing them from navigation.

Severity: Minor

Reported as: Misused role for site navigation

A control that takes users to another page must be a link, not a menu item.

When a menu or its items change the page's URL, assistive technology presents links as commands. Screen reader users have to operate them with the arrow keys instead of their usual link commands, and can't open a destination in a new tab or find it in a list of the page's links.

Build site navigation as a <nav> element containing a list of links, and use disclosure buttons to show and hide nested lists.

Severity: Serious

Reported as: Menu button has no associated menu

A parent menu item that declares a submenu must have one, with role="menu".

When an item carries aria-haspopup but no submenu follows it, or the submenu has no menu role, screen reader users are told a submenu exists and can't reach it, or reach content that doesn't behave like a menu.

Place the submenu immediately after its parent item, give it role="menu", and name it from the parent item with aria-labelledby.

Severity: Critical

Reported as: Aria-expanded value did not change

A parent menu item's aria-expanded value must change to "true" when its submenu appears and to "false" when it disappears.

When the submenu opens but the value stays "false", assistive technology reports a closed submenu that's on screen, so screen reader users don't know there are items to move into.

Update aria-expanded in the same code that shows and hides the submenu.

Severity: Serious

Reported as: Missing aria-expanded attribute

A parent menu item must carry an aria-expanded attribute so the state of its submenu can be reported.

When the attribute is missing, assistive technology has no state to report, so screen reader users can't tell whether the submenu is open or closed.

Set aria-expanded="false" on the parent item when the page loads, and keep it in step with the submenu.

Severity: Serious

Reported as: Menu is not an immediate sibling of its launcher

A submenu should be the element immediately after its parent menu item in the DOM.

When other elements come between a parent item and its submenu, or the submenu sits elsewhere in the page, assistive technology may not associate the two. Screen reader users reading through the page no longer hear the submenu's items right after the item that opens them.

Move the submenu directly after its parent item, inside the same menu or menubar, as in the Menubar With Submenus example.

Severity: Minor

Reported as: Unexpected interactives in menu

A menu must hold only interactive elements with a menu item role.

When a text field, a checkbox, a slider or another control sits among the items, the menu's arrow keys skip it, or users reach it without knowing how to operate it, and screen reader users hear a control the menu pattern doesn't expect.

Give each command a menu item role, using menuitemcheckbox or menuitemradio for a choice, and move any other control out of the menu, for example into a dialog the menu opens.

Severity: Minor

Reported as: Avoid aria-owns

A menu or menubar should hold its items in the DOM, directly or inside a group, in the order the arrow keys move through them, rather than claim them with aria-owns.

When items rendered elsewhere are owned, assistive technology that honors the attribute places them after the menu's own items, and assistive technology that doesn't reports them outside the menu. Screen reader users then hear the items in a different order from the one the arrow keys follow, or find items the menu doesn't count.

Render the items inside the menu, and when a framework portals a popup menu, portal the whole menu. Place each submenu immediately after its parent item, and when the parent item references it, use aria-controls rather than aria-owns.

Reported as: Invalid aria-owns values

When a menu uses aria-owns, each element it references should have the menuitem, menuitemcheckbox, menuitemradio, group, or separator role, and a group should reference only menu items.

When an owned element has another role, such as a plain button or a listitem, the menu's structure no longer adds up. The item count and positions come out wrong, and the arrow keys can reach an element the menu doesn't handle. An element owned by two containers, or two containers that own each other, leaves the structure undefined.

Reference only elements with those roles, and own each element from one container.

Reported as: Composite not in focus sequence

One item of a menubar must be in the tab order.

When every item has tabindex="-1", or the items are elements that can't take focus, keyboard users can't reach the menubar, so none of its commands are available to them.

Give the first item tabindex="0" and the others tabindex="-1". Alternatively, make the menubar container focusable and indicate the focused item with aria-activedescendant.

Severity: Critical

Reported as: Composite unpredictable focus

When focus enters a menubar, it must land on the first item, or on the item that last had focus.

When Tab puts focus somewhere else, such as on a middle item or on the menubar container with no item focused, keyboard users start from an unexpected place. Screen reader users don't hear the item they expect, or hear no item at all.

Keep tabindex="0" on the first item until the user moves, and then on the item they last focused. When using aria-activedescendant, set it to that item as the menubar receives focus.

Severity: Serious

Reported as: Redundant focusable children

A menubar must have only one item in the tab order.

When every item has tabindex="0", or native focusable elements keep their default focus behavior, Tab stops at every item. Keyboard users have to press Tab through the whole menubar to get past it, and nothing tells them to use the arrow keys instead.

Set tabindex="-1" on every item except the one that holds the tab stop, and move tabindex="0" as focus moves.

Severity: Moderate

Reported as: Focus on menu open

Opening a submenu from the keyboard must move focus into it.

When focus stays on the parent item after the submenu opens, keyboard users see options they can't reach with the keys they expect, and screen reader users aren't told the submenu has opened.

When Enter, Space, or an arrow key opens the submenu, move focus into it.

Severity: Serious

Reported as: Focus on menu close

Closing a submenu with Escape must return focus to the parent item that opened it.

When focus goes somewhere else, such as to the top of the page, keyboard users lose their place in the menu and have to find their way back to it. Screen reader users may not know the submenu has closed.

On Escape, hide the submenu, set the parent item's aria-expanded to "false", and move focus to the parent item.

Severity: Moderate

Reported as: Invalid focus position on menu open

Opening a submenu from the keyboard must put focus on its first item.

When focus lands on a later item, or on the submenu container with no item focused, users start partway through the options and may miss the items above. Screen reader users hear an item without knowing where it sits in the list.

Focus the first item each time a submenu opens. The one exception is Up Arrow opening a submenu from a menubar, which focuses the last item.

Severity: Moderate

Reported as: Menu unexpected focus shift

Each arrow key press in a menu must move focus to the adjacent item in that direction.

When an arrow key skips items, jumps to an unrelated element, or sends focus to the top of the page, keyboard users lose their place, and screen reader users can't form a picture of the menu.

Move focus to the next or previous item on each press, in the order the items appear, and keep focus inside the menu until Tab or Escape takes it out.

Severity: Critical

Reported as: Disabled menu item not discoverable

A disabled menu item must stay reachable with the arrow keys that move through its menu.

When the arrow keys pass over disabled items, keyboard and screen reader users never land on them, so they don't learn that those commands exist but are unavailable for now.

Include disabled items in the set the arrow keys move through, mark them with aria-disabled="true", and ignore attempts to run them.

Severity: Minor

Reported as: Arrow key navigation failed

A menu should move focus with the arrow keys that match its layout.

When the arrow keys don't move focus, or only the keys for the other direction do, keyboard users can't reach the items past the one that has focus.

Handle Up Arrow and Down Arrow in a vertical menu, and Left Arrow and Right Arrow in a horizontal menubar, on keydown on the menu container.

Reported as: Aria-expanded value did not change

A parent menu item must update its aria-expanded value when the keyboard opens or closes its submenu.

When the submenu opens on Enter or an arrow key but aria-expanded stays "false", screen reader users aren't told their key press opened anything, and hear a closed state for a submenu they're now inside.

Set aria-expanded in the same function that shows and hides the submenu, so key presses, clicks, and Escape all update it.

Severity: Serious

Reported as: Missing aria-expanded attribute

A parent menu item must carry an aria-expanded attribute, so opening its submenu from the keyboard has a state to update.

When the attribute is missing, screen reader users who press Enter, Space, or an arrow key get no confirmation that the submenu opened, or that it closed again.

Add aria-expanded="false" to the parent item, and set it to "true" when the keyboard opens the submenu.

Severity: Serious

Reported as: Menuitemcheckbox Not Toggled

A checkable menu item must change its aria-checked value when it's operated, and Space must do so without closing the menu.

When Space leaves the value unchanged, or closes the menu without toggling the item, keyboard users can't set the option. Screen reader users get no confirmation that anything happened.

Handle Space on each checkable item: toggle aria-checked on a menuitemcheckbox, or check a menuitemradio and uncheck the others in its group, and keep the menu open.

Severity: Critical

Reported as: Menuitemcheckbox has no aria-checked attribute

A menuitemcheckbox or menuitemradio must carry aria-checked.

When the attribute is missing, assistive technology can't report whether the option is on, so screen reader users don't know the current setting before they change it.

Set aria-checked="true" or "false" on every checkable item from the start, and keep it in step with the setting.

Severity: Critical

Reported as: Deprecated keypress listener

A menu's key handling should use keydown or keyup, not keypress.

When a handler listens for keypress, keys the browser doesn't send through that event go unanswered, and keyboard users find the menu ignoring keys it's meant to respond to.

Replace each keypress listener with a keydown listener, and read the key from event.key.

Severity: Minor

Under 4.1.2 Name, Role, Value, a menu and its items carry their roles, each item has an accessible name, the disabled state is declared correctly, checkable items carry aria-checked, and site navigation uses links rather than menu items.

Under 1.3.1 Info and Relationships, a menu contains menu items and has a name of its own, parent items report their submenus with aria-expanded, each submenu is associated with its parent item, disabled items stay reachable, a menubar has a single tab stop, and opening a submenu focuses its first item.

Under 2.1.1 Keyboard, aria-orientation matches the arrow keys, a menubar is reachable with Tab and focus lands on its first item, focus moves into a submenu and returns on Escape, the arrow keys move focus between items, and Space toggles checkable items. Distinct item names, a valid aria-haspopup and aria-orientation, and a submenu placed right after its parent item map to no WCAG success criterion and are best practices.

Severity reflects how much an issue gets in users' way. Critical issues stop users outright:

• A menu or menu item without its role, or a menu item without a name
• An aria-expanded value that contradicts the screen
• A parent menu item with no submenu
• A menubar keyboard users can't reach
• Arrow keys that move focus to the wrong place
• A checkable menu item that doesn't toggle or report its state

Serious issues mislead or strand users:

• A menu with no menu items, or with no name of its own
• Menu items that share a name
• An aria-orientation value that contradicts the arrow keys
• A missing or unchanging aria-expanded value
• A wrong disabled state
• Menu roles used for site navigation
• Focus that lands away from the first menu item, or doesn't move into a submenu that opens

Moderate issues weaken orientation:

• A missing aria-haspopup
• Every menu item in the tab order
• Focus that isn't restored on Escape, or lands on the wrong item when a submenu opens

Minor issues break a convention without blocking the task:

• An aria-haspopup or aria-orientation value that doesn't fit
• A disabled menu item the arrow keys skip
• A submenu placed away from its parent item

Four checks carry no severity: the two general checks on aria-owns, and the sanity checks on where the menu item role sits and on arrow-key navigation.