aria-expanded — Indicating Expandable and Collapsible State

In this tutorial, you will learn about aria. We cover key concepts, practical examples, and best practices to help you master this topic.

aria-expanded indicates whether an expandable element like an accordion, dropdown menu, or disclosure widget is currently open or closed, helping screen reader users understand the toggle state.

In this tutorial, you'll learn how to implement aria-expanded correctly in your ARIA components.

What You'll Learn

By the end of this lesson, you'll understand when to use aria-expanded, how to toggle it with JavaScript, how it relates to aria-controls, and how to test the announcement.

Why It Matters

Without aria-expanded, screen reader users cannot tell whether a button will open or close content. They must guess, which makes navigation unpredictable.

Real-World Use

Doda Browser's sidebar menu uses aria-expanded on each section header to indicate whether the subsection is expanded, and Durga Antivirus Pro uses it on scan detail toggles.

Expand/Collapse Flow

flowchart LR
  A[Button clicked] --> B{Is content visible?}
  B -->|No| C[Show content]
  B -->|Yes| D[Hide content]
  C --> E[Set aria-expanded='true']
  D --> F[Set aria-expanded='false']
  E --> G[Screen reader announces expanded]
  F --> H[Screen reader announces collapsed]

How aria-expanded Works

aria-expanded is set on the element that controls the expandable content, not on the content itself:

<button aria-expanded="false" aria-controls="details-1">
  Show scan details
</button>
<div id="details-1" hidden>
  <!-- collapsible content -->
</div>

The screen reader announces: "Show scan details, button, collapsed".

Toggling With JavaScript

Keep aria-expanded synchronized with the visible state:

function toggleAccordion(button) {
  const isExpanded = button.getAttribute('aria-expanded') === 'true';
  button.setAttribute('aria-expanded', !isExpanded);
  const contentId = button.getAttribute('aria-controls');
  document.getElementById(contentId).hidden = isExpanded;
}

Accordion Patterns

For accordions where only one section can be open:

function openSection(button) {
  // Close all sections
  document.querySelectorAll('[aria-expanded="true"]').forEach(el => {
    el.setAttribute('aria-expanded', 'false');
    const id = el.getAttribute('aria-controls');
    document.getElementById(id).hidden = true;
  });
  // Open this section
  button.setAttribute('aria-expanded', 'true');
  const contentId = button.getAttribute('aria-controls');
  document.getElementById(contentId).hidden = false;
}

Common Mistakes

• Setting aria-expanded on the content panel: aria-expanded goes on the controlling element, not the panel.
• Forgetting aria-controls: Without the ID reference, users cannot associate the button with its content.
• Not syncing with hidden state: If the content is visible but aria-expanded="false", users get wrong information.
• Using aria-expanded on non-interactive elements: Only interactive controls should have this attribute.
• Omitting the CSS transition: Visual changes should smoothly follow the expanded state.

Practice and Challenge

1. Which element gets aria-expanded? The element that controls the expandable content, not the content itself.

2. What does aria-expanded="true" indicate? The content is currently visible or expanded.

3. What attribute pairs with aria-expanded to link control to content? aria-controls referencing the content element's ID.

4. How do you associate a button with its expandable panel? Set aria-controls on the button to the panel's ID.

5. Challenge: Build a complete accordion component with three sections. Each section uses aria-expanded and aria-controls, and only one section can be open at a time.

FAQ

Mini Project

Create a FAQ page with an accordion pattern. Each FAQ item has a button with aria-expanded and aria-controls. Clicking a question expands its answer and collapses others. Test with a screen reader.

What's Next

Continue to aria-selected to learn how to indicate selected options in lists.