Search topics
Navigation menus built as an app's menu bar
A site's header is marked up with role="menubar": its submenu buttons are menu items but its plain links are not, so a screen reader counts only some of them.
<div role="menubar"> The problem
Screen reader users are told the menu has fewer items than it shows, and the links left out of it are reached only by Tab, outside the menu
A shop's header has four items in a row: Home, Shop, Journal and Help. Shop and Help open a list of pages; Home and Journal are plain links. With a mouse it all works. The header was built with a menu bar component, the kind a UI library offers for an app's File, Edit and View menus, so Shop and Help are menu items, and Home and Journal, which the component has no item type for, sit beside them as ordinary links.
A screen reader user tabs into the header. On Shop they hear "menu bar, Shop, menu item, collapsed, 1 of 2". Two items, in a header that shows four. They press Right Arrow, as a menu bar asks, and land on Help, "2 of 2", past Journal. Home and Journal are still there, and Tab reaches them, but each is read as "link" with no place in the menu: from what they hear, the menu is two items with two stray links beside it.
The keyboard is no simpler. The component gives the bar one Tab stop, on whichever menu item was last used, so Tab goes Home, Shop, Journal and on into the page. Help is reached only with the arrow keys from Shop, and Right Arrow from Shop skips Journal.
WCAG 1.3.1 Info and Relationships asks that structure shown on screen can also be read by assistive technology. On screen, the four items are one row, one menu. In the code, role="menubar" says the row is a menu bar, and ARIA lets a menu bar hold only menu items (and groups and separators of them). The two submenu buttons have role="menuitem", so they are its items; Home and Journal are links, a role a menu bar can't own, so they are not its items. A screen reader reports the structure the code gives it: a menu bar of two items, positions 1 of 2 and 2 of 2, and two links inside it that are left out of the count. The relationship a sighted visitor sees, four items in one menu, isn't there for anyone else.
The keys follow the same structure. A menu bar is meant to be one Tab stop, moved along with the arrow keys, so the component keeps a roving tabindex: 0 on one menu item and -1 on the other. The links keep their own Tab stops and are not in the arrow-key order. Everything can still be reached, Help by Right Arrow, so 2.1.1 Keyboard passes, but which key reaches which item now depends on how each one was marked up.
A menu bar also changes how a screen reader works. NVDA, for one, switches to focus mode as soon as focus lands in a menu bar or a menu item: it stops reading the page with its own keys and passes the arrow keys to the page's script, as it does in an app, because a menu bar promises that its script handles them.
2 of 10 groups affected
- No vision (affected)
- Low vision (not affected)
- Colour vision (not affected)
- No hearing (not affected)
- Hard of hearing (not affected)
- No speech (not affected)
- Motor (affected)
- Reach, strength (not affected)
- Cognitive (not affected)
- Seizures (not affected)
- Without vision Screen reader users hear a menu bar of two items, "Shop, menu item, 1 of 2", in a header of four, and Home and Journal are read as links outside it. Moving along the bar with the arrow keys never reaches them, so the menu sounds smaller than it is.
- Limited manipulation Keyboard users find that Tab stops on Home, Shop and Journal but never on Help, which only the arrow keys from Shop reach; Right Arrow from Shop also jumps past Journal. Nothing on screen says which key reaches which item.
axe and Lighthouse do report this one: the menu bar fails aria-required-children, "Certain ARIA roles must contain particular children". The message names neither the links nor the navigation (its detail lists only the a elements, as "children which are not allowed"), so it reads like a list problem, and the obvious way to clear it is to add role="menuitem" to the links. An AI coding tool asked to fix the error is likely to do exactly that. The error goes, and the header is now a complete app menu bar, which is the second fix below: it passes, and axe reports nothing on it, but it is still the wrong pattern for a site's navigation. Nothing in a scan asks whether the menu bar should be there at all.
The audit reports a menu bar that holds links which are not its menu items, and names them, in place of axe's message. A menu bar whose links are all menu items is sent to review as a lead: no criterion fails, so a person decides whether it is the site's navigation or an app's menu. Listening to the header with a screen reader, and tabbing through it, is still how to confirm either.
Try it
Move through the menu with Tab, then with the arrow keys, and listen to the count
Tab stops on Home, Shop and Journal, never on Help, and on Shop the panel says “1 of 2”: the menu bar counts only Shop and Help. From Shop, Right Arrow jumps to Help, past Journal. Then apply a fix and count again.
Broken Can you fix this?
Screen reader says:
(Tab to the menu)
The fix
Make the navigation links, with a button for each submenu
<header> <div class="menu" role="menubar"> <a href="/" aria-current="page">Home</a> <button type="button" role="menuitem" aria-haspopup="menu" aria-expanded="false" aria-controls="shop-menu" tabindex="0">Shop</button> <a href="/journal">Journal</a> <button type="button" role="menuitem" aria-haspopup="menu" aria-expanded="false" aria-controls="help-menu" tabindex="-1">Help</button> </div> <div id="shop-menu" role="menu" aria-label="Shop" hidden> <a href="/shop/lamps" role="menuitem" tabindex="-1">Lamps</a> <a href="/shop/chairs" role="menuitem" tabindex="-1">Chairs</a> <a href="/shop/rugs" role="menuitem" tabindex="-1">Rugs</a> </div> <div id="help-menu" role="menu" aria-label="Help" hidden> … </div></header>What is wrong3 points
- Home and Journal are links inside a menu bar, which can own only menu items, so they are not its items. A screen reader counts two items, Shop "1 of 2" and Help "2 of 2".
- Right Arrow moves between Shop and Help only, so it skips Journal.
- Tab stops on Home, Shop and Journal, and never on Help, which has
tabindex="-1"until Right Arrow reaches it.
A nav with links and submenu buttons
<header> <nav aria-label="Main"> <ul class="menu"> <li> <a href="/" aria-current="page">Home</a> </li> <li class="has-sub"> <button type="button" aria-expanded="false" aria-controls="shop-menu">Shop</button> <ul id="shop-menu" tabindex="-1" hidden> <li> <a href="/shop/lamps">Lamps</a> </li> <li> <a href="/shop/chairs">Chairs</a> </li> <li> <a href="/shop/rugs">Rugs</a> </li> </ul> </li> <li> <a href="/journal">Journal</a> </li> <li class="has-sub"> <button type="button" aria-expanded="false" aria-controls="help-menu">Help</button> <ul id="help-menu" tabindex="-1" hidden> … </ul> </li> </ul> </nav></header>How it is fixed5 steps
- Replace the menu bar with a
navnamed Main, holding a list with oneliper item. A screen reader announces the navigation and a list of four items, and every item is in it. - Keep Home and Journal as plain links, and make Shop and Help plain buttons: no
role, noaria-haspopup, notabindex. Each is its own Tab stop, in the order shown, and is read as what it is. - Put each submenu's list straight after its button, with
aria-expandedon the button kept in step withhiddenon the list, andaria-controlspointing at it. Tab goes from the button into the open list. - Close an open list on Escape, with focus back on its button, and when focus leaves its item. Put
tabindex="-1"on the list so a click inside it doesn't count as leaving. - Remove the menu bar's key handling. Tab moves through the navigation; nothing needs the arrow keys.
This fixes the Before and passes 1.3.1: the list holds every item, and nothing is left outside it. Hover-only dropdowns, or ones that never say they are open explains the button, its state and the two ways it closes in detail.
Why this fix: Use native HTML first
Use the nav. It passes on its own, with no keys to learn: every item is a Tab stop, links are read as links, and the list gives the right count. It is built from HTML that already does the work, so the menu bar's key script goes, and the button script left is the one the hover dropdowns guide already teaches. Making every link a menu item is the quick way to clear the scan, and it is the menu bar pattern done properly, but it keeps people in an app's menu where they expect a site's links. The ARIA Authoring Practices' own navigation menubar example says the disclosure pattern "is better suited for most web sites because few sites need the additional keyboard functionality required to support the ARIA menubar and menu roles." Keep a menu bar only where the bar really is an app's menu, with commands such as File and Edit, rather than pages.
Component libraries usually offer both. In Radix UI, Menubar is "a visually persistent menu common in desktop applications", whose triggers are buttons with role="menuitem" and no item type for a plain link, which is how links end up beside them as in the Before. Navigation Menu is "a collection of links for navigating websites": it renders a nav, a list, and buttons with aria-expanded for its submenus, and its documentation says it "should not be confused with menubar". The shadcn/ui components wrap both under the same names. If your header uses Menubar, switch the component rather than adding roles to the links.
Other parts of the header each need their own answer.
- Arrow keys: optional. You may let Left and Right Arrow move between the top-level items as well, but keep each one a Tab stop, so people who don't know about the arrow keys miss nothing.
aria-haspopup: leave it off the submenu buttons. On a button it announces a menu, and the list it opens is a list of links.- The current page: keep
aria-current="page"on its link, as navigation that marks the current page only by its look explains. It is read on a link in a list as it was in the menu bar. - An item that is both a page and a submenu: keep the link and a separate button side by side; dropdown parent links that open the submenu, not the page covers it.
- A real app menu on the same page, such as an editor's toolbar of File and Edit menus, stays a menu bar. Action menus behind a More button are covered in action menus that open silently, out of keyboard reach, where
role="menu"is right.
Verify the fix
4 checks, no mouse.
Test with: Screen reader, Keyboard
Record the OS, browser and assistive-technology versions, the build, the date, and the actual result of each step. Repeat after the shared header component changes.
Limits
This guide is about the roles a site's navigation is given. A submenu that opens only on hover, or a button that never says whether its list is open, is covered in hover-only dropdowns, or ones that never say they are open. The script is a minimal sketch without animation, hover opening or nested levels. Test the complete journey, including your narrow-screen menu, with your target assistive technology.
This is a recreated teaching example, not a finding about a named client. The code is a starting pattern: test it in your own product. No completed assistive-technology test is claimed here.
References
- WCAG Understanding: info-and-relationships (opens in a new tab)
- w3.org: wai-aria-1.2 (opens in a new tab)
- ARIA APG: menubar (opens in a new tab)
- ARIA APG: menubar-navigation (opens in a new tab)
- ARIA APG: disclosure-navigation (opens in a new tab)
- developer.mozilla.org: menu_role (opens in a new tab)
- github.com: browseMode.py (opens in a new tab)
- radix-ui.com: menubar (opens in a new tab)
- radix-ui.com: navigation-menu (opens in a new tab)
- inclusive-components.design: menus-menu-buttons (opens in a new tab)
EaseWeb service
Fixed it? Keep it from coming back.
I turn guides like this one into rules your coding agents follow and checks your CI runs. Then I retest by hand with a keyboard and screen readers, periodically.