Order 1042
Delivered on 14 October
Search topics
Action menus that open silently, out of keyboard reach
An Actions button drops down a menu of clickable divs, but says nothing about the menu, leaves focus on the button, and gives the actions no role, no Tab stop and no arrow keys, so a keyboard can't reach them and a screen reader isn't told anything opened.
<div class="item">Download invoice</div> 01
The problem
Keyboard users can open the Actions menu but can't reach anything in it, and screen reader users aren't told that the button opens a menu or that one has opened.
A shop's order history shows each order on a card, with an Actions button that drops down four things to do with it: Buy again, Return items, Download invoice and Report a problem. Click Actions and the menu opens under the button; click Download invoice and the invoice downloads. The button is a real button, so Tab reaches it and Enter opens the menu. But focus stays on Actions, and the actions are divs with a click handler, so the next Tab passes the open menu and lands on View all orders, under the card. Down Arrow scrolls the page. Nothing in the menu can be reached without a mouse. A screen reader says "Actions, button", and when Enter is pressed nothing new is announced: not that the button opens a menu, and not that one has opened. Reading on with its own keys, it finds the four actions as plain words, with no role to say they can be pressed or that they belong to the button.
The team then makes it a menu the quick way: aria-haspopup="menu" on the button, role="menu" on the panel and role="menuitem" on each action, and nothing else. A screen reader now says the button opens a menu, but pressing it changes nothing more: focus stays on the button, nothing says the menu is open, Tab still passes every item, and the arrow keys a menu promises do nothing.
Success criterion 2.1.1 Keyboard asks that everything the mouse can do, the keyboard can do. The mouse runs an action by clicking a div, and a div takes no focus, so the keyboard can open the menu but can't reach anything in it. Every action in the menu, Download invoice included, needs a mouse. The menu roles change nothing here: a role says what an element is, not how it behaves, so the items still take no focus, and no script answers the arrow keys.
Success criterion 4.1.2 Name, Role, Value asks that controls expose their role and state, and that changes to them reach assistive technology. The button exposes its name and role, but not that it opens a menu, or whether the menu is open, so pressing it changes nothing a screen reader can report. The actions expose no role at all: a click handler gives a div no role in the accessibility API, which is failure F59. With the roles added, the button says it opens a menu, but still not whether it is open, and focus stays on the button, so opening the menu is still silent. Roles without the behaviour they promise are failure F15: custom controls that use the accessibility API incompletely.
Action menus sit on order histories, address books, file lists, team settings and comments, often one on every row, and on a phone the same button often holds the actions there is no room to show. Whatever is behind it is out of reach for anyone who can't click it, and unknown to anyone who can't see it open.
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)
- Limited manipulation Keyboard and switch users can open the menu, but focus stays on the button and Tab passes the actions by, so Download invoice, Return items and the rest can't be run without a mouse. Adding menu roles to the same divs changes nothing for them: no key moves into the menu.
- Without vision Screen reader users hear "Actions, button" and then nothing when they press it, so they can't tell that a menu opened. Reading on, they meet the actions as words with no role, or, with the menu roles added, as menu items that focus never reaches.
The first menu has a real button with a name, and divs with no role, so axe has nothing to report. The menu roles pass axe too: every menuitem sits in a menu, and each has a name. axe checks that the roles fit together, not whether focus ever reaches an item or what a key does.
The audit presses the keys. It finds buttons that say they open a menu with aria-haspopup, and buttons named More, Actions or Options, or with a class such as kebab, overflow or dropdown, outside the site's navigation and header. It opens each with Enter on a freshly loaded page, and looks at what appeared. If focus doesn't move into the menu, Down Arrow and Tab don't reach it either, and none of its actions is a Tab stop, that is reported. A role="menu" that takes focus, but whose arrow keys, Home and End never move focus on from the item it reached, is reported too. A button that leaves focus on itself as its menu opens, with no aria-expanded, is reported, and so is an aria-expanded that stays false. A menu whose items are Tab stops, with arrow keys that do nothing, goes to review. A menu button with any other name and no telling attribute or class is not found, nor is one in a header, and no check can tell whether the actions are the ones people need.
The second menu is what an AI fix can produce: it adds the roles to the existing divs and stops there, and the result passes axe. A fix can also put tabindex="0" on every item, which makes each one a Tab stop inside a menu whose arrow keys do nothing.
02
Try it
Open Actions and reach Download invoice using only the keyboard.
Broken 1: Tab to Actions and press Enter. The menu opens, but focus stays on the button, the panel below says nothing new, and the next Tab passes the menu by.
Broken 2: the same divs, with menu roles added. The panel now says the button opens a menu, but Enter still leaves focus behind, and neither Tab nor the arrow keys reach an item.
Apply the fix. In the menu button, Enter moves focus to the first action, and the arrow keys, Home, End and Escape work; in the disclosure, the next Tab goes from Actions into the list.
Broken Can you fix this?
Screen reader says:
(Tab to Actions)
03
The fix
Make the button say that it opens something and whether it is open, and put every action where the keyboard reaches it: in a menu that takes focus and the arrow keys, or in plain buttons straight after the button.
- 1The button says that it opens a menu, or whether it is expanded, and says it again as it opens and closes.
- 2Every action is a button, a link or a menu item that the keyboard can reach.
- 3A role="menu" gets everything the role promises: focus moves in, the arrow keys move, Escape goes back; without them, use plain buttons.
A button and a dropdown of clickable divs
<article class="order"> <h2>Order 1042</h2> <p>Delivered on 14 October</p> <div class="actions"> <button type="button" class="actions-button">Actions</button> <div class="actions-menu" hidden> <div class="item" data-action="buy-again">Buy again</div> <div class="item" data-action="return">Return items</div> <div class="item" data-action="invoice">Download invoice</div> <div class="item" data-action="report">Report a problem</div> </div> </div></article>A menu button
<article class="order"> <h2>Order 1042</h2> <p>Delivered on 14 October</p> <div class="actions"> <button type="button" class="actions-button" id="order-1042-actions" aria-haspopup="menu" aria-expanded="false" aria-controls="order-1042-menu">Actions</button> <div class="actions-menu" id="order-1042-menu" role="menu" aria-labelledby="order-1042-actions" hidden> <button type="button" role="menuitem" tabindex="-1" data-action="buy-again">Buy again</button> <button type="button" role="menuitem" tabindex="-1" data-action="return">Return items</button> <button type="button" role="menuitem" tabindex="-1" data-action="invoice">Download invoice</button> <button type="button" role="menuitem" tabindex="-1" data-action="report">Report a problem</button> </div> </div></article>The button opens the menu, but nothing moves focus into it, and the actions answer only click and take no focus, so the keyboard stops at the button. Nothing in the markup says the button opens anything, whether it is open, or that the words under it are actions.
This is the menu button pattern of the ARIA Authoring Practices. aria-haspopup="menu" makes a screen reader say that the button opens a menu, and aria-expanded says whether it is open. Enter, Space or a click opens it and moves focus to Buy again, so a screen reader announces the menu, named after its button, and the item, usually with its place: 1 of 4. The items are buttons, so Enter and Space run them with no key handling to write, and role="menuitem" gives them the role a menu holds. tabindex="-1" keeps them out of the Tab order, and the script moves focus between them: Down and Up Arrow, wrapping round at the ends, Home and End. Escape closes the menu and puts focus back on Actions, and so does running an action. Tab leaves the menu for the next thing on the page, and the menu closes behind it.
Both pass. The disclosure is the smaller change, and it suits a few actions on a page of a site, like this one: its actions are buttons that every browser, screen reader and voice control program already knows, it needs one attribute and a toggle, and people move through it with Tab as they do through the rest of the page. Build the menu button where the page works like an application, such as a mail client, a file manager or an editor, where people expect actions to behave like the menus of their operating system, and where each action as a Tab stop would make every row slow to pass. Then it needs all of it: the roles, the open state, focus moved in, and every key. The ARIA Authoring Practices' Actions menu example is the model. If the card has room, consider not hiding the actions at all: a button for each one, as right-click, long-press and swipe actions with no button shows.
On a page of orders, every card's button says Actions. Keep the word on the button and add which order it is for, with aria-describedby pointing at the card's heading, or hidden text after the word (Actions <span class="visually-hidden">for order 1042</span>), so the name still starts with what is shown, as buttons and links named differently from their text explains. The menu takes its name from the button through aria-labelledby.
The menu button pattern allows a few more things. Down Arrow on the button may open the menu on its first item, and Up Arrow on its last. A letter may move to the next item that starts with it, which matters in long menus. An action that is unavailable stays in the menu with aria-disabled="true", so people learn it exists, and can still be reached with the arrow keys. An action that switches something on and off is a menuitemcheckbox with aria-checked. Keep submenus out of action menus: each one adds keys to get right, Right Arrow to open it and Left Arrow to leave it, and a menu to place on screen.
A role="menu" holds menu items and nothing else: no links, fields or headings beside them. If a menu needs those, it is a disclosure or a dialog. Links to other pages, such as View invoice, can sit in the disclosure's list as links; in a menu they need role="menuitem" too.
The popover attribute can carry either menu. The browser then closes it on Escape and on a click outside, puts focus back on the button after Escape, and draws it above the page, where no overflow: hidden on a card cuts it off. The menu in right-click, long-press and swipe actions with no button is built that way. A popover is centred on the screen until you place it, with CSS anchor positioning or a few lines of script. Without it, check that the card doesn't clip the menu. If the menu is rendered at the end of the page, as some component libraries do, focus moved into it by script still reaches it, but a disclosure list there is reached only after everything else, as floating buttons and panels that keyboard focus reaches last explains. Where focus goes when either one closes is covered in search panels that close on Tab and drop keyboard focus.
Menu components in libraries vary: some move focus and handle every key, some only add the roles. Check the one you use with the keyboard before relying on it.
04
Verify the fix
5 checks, no mouse.
Test with: Keyboard, Screen reader, Forced colors, Zoom
0 of 5 checked
Record the OS, browser and assistive-technology versions, the build, the date, and the actual result of each step. Repeat after the menu, its component or its library changes.
How screen readers handle aria-expanded and aria-haspopup="menu"
Limits
This is a starting pattern, not a guarantee for every application. The scripts are minimal sketches: one menu per page, no type-ahead, no unavailable items, no submenus. A drop-down of links across the top of a site is navigation, a different pattern, covered in hover-only dropdowns, or ones that never say they are open; a drop-down that picks a value, such as a size, is a select, covered in custom dropdowns that keyboards and screen readers can't use. Menus that only a right-click or a long press opens are covered in right-click, long-press and swipe actions with no button, and a button that is only an icon, such as three dots, also needs a name, as icon-only buttons with no accessible name explains. Test the complete journey 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
- ARIA APG: menu-button (opens in a new tab)
- ARIA APG: menu-button-actions (opens in a new tab)
- ARIA APG: menubar (opens in a new tab)
- ARIA APG: disclosure (opens in a new tab)
- WCAG Understanding: keyboard (opens in a new tab)
- WCAG Understanding: name-role-value (opens in a new tab)
- WCAG Technique F59 (opens in a new tab)
- WCAG Technique F15 (opens in a new tab)
- w3.org: wai-aria-1.2 (opens in a new tab)
- inclusive-components.design: menus-menu-buttons (opens in a new tab)
Keep this fixed as your code changes.
Turn guides like this into rules your coding agents and CI follow, then have the result retested with a keyboard and screen readers.