aria-expanded

`aria-expanded` is a WAI-ARIA state attribute that communicates whether a collapsible section of content is currently open or closed. It is placed on the interactive element that controls the collapsible content, typically a button, to inform assistive technologies of the current state and allow users to predict what will happen when they activate the control. Collapsible content patterns are everywhere on the modern web: accordions, dropdown menus, expandable navigation items, tree views, disclosure widgets, and FAQ sections. For sighted users, the expanded or collapsed state is often conveyed through visual cues like arrows, plus/minus icons, or animation. `aria-expanded` provides the equivalent information for screen reader users. When a screen reader encounters a button with `aria-expanded="false"`, it announces something like "Menu, collapsed, button." When the user activates the button and the attribute changes to `"true"`, the screen reader announces "Menu, expanded, button." This clear state communication allows users to understand and operate collapsible interfaces confidently.

Without `aria-expanded`, screen reader users have no way to know whether activating a control will reveal or hide content. They press a button and must then explore the surrounding content to determine what, if anything, changed. Did a menu appear? Did content expand below? Is there new content to interact with? This guesswork is time-consuming and frustrating. WCAG Success Criterion 4.1.2 (Name, Role, Value) requires that the states and properties of user interface components can be programmatically determined and set. For any control that toggles visibility of content, `aria-expanded` is the standard way to fulfill this requirement. The attribute also helps users build a mental model of the interface. When navigating an accordion with five sections, knowing that two are expanded and three are collapsed helps the user understand the page structure and decide where to focus their attention.

The basic implementation involves a trigger element with `aria-expanded` and a content panel that is shown or hidden: ```html <button aria-expanded="false" aria-controls="faq-answer-1"> What is your return policy? </button> <div id="faq-answer-1" hidden> <p>You can return items within 30 days of purchase...</p> </div> ``` When the user clicks the button, JavaScript toggles both the attribute and the content visibility: ```javascript const button = document.querySelector('button'); const content = document.getElementById('faq-answer-1'); button.addEventListener('click', () => { const isExpanded = button.getAttribute('aria-expanded') === 'true'; button.setAttribute('aria-expanded', String(!isExpanded)); content.hidden = isExpanded; }); ``` **Key implementation patterns:** **Accordions** use a series of buttons each with `aria-expanded`, controlling their respective content panels. Each button independently tracks its expanded state. **Dropdown menus** place `aria-expanded` on the menu button. When expanded, the menu items become visible and navigable. When collapsed, they are hidden. **Tree views** use `aria-expanded` on parent nodes to indicate whether their children are visible. This is combined with roles like `treeitem` and `group`. **Navigation menus** with nested submenus use `aria-expanded` on parent menu items to indicate submenu visibility. **Common mistakes to avoid:** - **Placing `aria-expanded` on the content panel** instead of the trigger. The user interacts with the trigger, so that's where the state belongs. - **Omitting the attribute entirely** instead of setting it to `"false"`. If an element controls collapsible content, it should always have `aria-expanded` with an explicit value. Omitting it implies the element is not an expand/collapse control. - **Forgetting to toggle the attribute** when the visual state changes. The attribute and the visual state must always be synchronized. - **Using `aria-expanded` on elements that don't control collapsible content.** Not every button needs this attribute. Only use it when the button actually toggles visibility of associated content. Pair `aria-expanded` with `aria-controls` to programmatically identify which element is being expanded. While screen reader support for `aria-controls` varies, it provides useful information for accessibility auditing tools and future-proofs your implementation.