Short answer: aria-expanded goes on the button that opens and closes something: true while the content is on screen, false while it isn’t. It lets screen readers announce the state. MDN recommends pairing it with aria-controls, and it doesn’t belong on elements that control nothing.
What aria-expanded does
MDN describes aria-expanded as the attribute that indicates whether a control is expanded or collapsed, and so whether the elements it controls are shown or hidden. It goes on the focusable control that toggles them, not on the content.
Menus, dialogs and accordion panels all work this way. aria-controls names the relationship between the control and the content, and aria-expanded gives the state. Native elements such as details and summary report their state without it, as our details and summary guide measured.
Where it goes
| Control | aria-expanded goes on | Also |
|---|---|---|
| A show and hide section | The button that toggles it | aria-controls with the section’s id |
| A navigation dropdown | The button that opens the list of links | Usually no menu role: a disclosure button |
| A menu of actions | The menu button | aria-haspopup set to menu or true |
| Content that never collapses | Nothing | The attribute signals control, so leave it out |
Based on MDN and the W3C’s authoring patterns for ARIA, read November 5, 2026.
MDN’s rule for buttons: a button that toggles a widget carries aria-controls with the widget’s id and aria-expanded with its current state. For a menu, the button has aria-expanded set to true while the menu shows, and false or nothing while it is hidden.
Navigation dropdowns are disclosures, not menus
The W3C’s navigation example uses the word menu in the everyday sense but avoids the menu role. That role promises the complex keyboard behavior assistive technologies expect from an application menu, which typical site navigation doesn’t need.
So each dropdown is a disclosure: a button that reveals a list of links and carries aria-expanded. Our website navigation guide covers what goes in those lists.
Keys and focus
The W3C disclosure pattern asks for two keys on the button: Enter and Space both open and close the content. Its navigation example adds two details: Escape closes an open dropdown when the focus is inside it, and moving the focus out closes it too.
The state has to follow every way of opening and closing. If a script closes the panel but leaves aria-expanded at true, screen reader users hear an open section that isn’t there. A wrong state is worse than none, as our what is ARIA guide shows.
How to add aria-expanded
- Use a button element for the control that opens and closes the content.
- Give the content an id and point aria-controls on the button to it.
- Set aria-expanded to false while the content is hidden.
- Switch it to true when the content shows, and back when it hides.
- Use a button so Enter and Space activate it, and let the same script update aria-expanded.
- For navigation, follow the W3C example: close the dropdown with Escape and when the focus leaves it.
- Check the state in the accessibility tree after each way of opening and closing.
What we found in our own header
On November 5, 2026, we tested the Services button in our header, on the home page and a guide, in both languages. It is a button element with aria-controls pointing to the panel it opens.
A click, Enter and Space all opened and closed the panel, and each time aria-expanded matched what was on screen: true with the panel open, false with it closed. Chrome’s accessibility tree reported the same state.
It also follows the W3C navigation example. Escape closed the open panel and left the focus on the button, and tabbing past the panel’s last link closed it as well.
Before you publish
- aria-expanded is on the control, not on the content.
- Its value matches what is on screen after every action.
- The control points to the content with aria-controls.
- Navigation dropdowns are disclosure buttons, unless they truly need menu behavior.
- Enter, Space and Escape behave as expected.
- Elements that control nothing don’t carry aria-expanded.
Rememberaria-expanded is a promise about what is on screen. Put it on the button, keep it true only while the content shows, and test every way of closing.
Our web design service builds menus and panels that report their state this way.
Quick answers about aria-expanded
What does aria-expanded do?
It tells assistive technology whether a control is expanded or collapsed, and so whether the content it controls is shown or hidden. MDN describes it this way, and a screen reader can announce the state when people reach the control.
Where does aria-expanded go?
On the control that opens and closes the content, usually a button, not on the content itself. MDN adds that the button should carry aria-controls with the id of the content it toggles.
Should a navigation dropdown use the menu role?
Usually not. The W3C’s navigation example uses disclosure buttons instead, because typical site navigation doesn’t need the complex keyboard behavior that assistive technologies expect from a menu.
Which keys should open and close a disclosure?
Enter and Space, according to the W3C disclosure pattern. In its navigation example, Escape also closes an open dropdown when the focus is inside it, and moving the focus out closes it too.
Can I put aria-expanded on any element?
Only on elements that control something that expands. MDN warns that the attribute signals control, so it shouldn’t appear on elements that don’t open or close anything.
Sources
Read on November 5, 2026. MDN Web Docs: ARIA: aria-expanded attribute. W3C Web Accessibility Initiative: Disclosure (Show/Hide) Pattern, Example Disclosure Navigation Menu and Menu Button Pattern. Our case: our own pages, read in a browser on November 5, 2026.