Accordions With Button and aria-expanded
Build a disclosure that announces open and closed.
Accordions With Button and aria-expanded is a free Web Accessibility Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Web Accessibility Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
What an Accordion Does
An accordion is a stack of headings that expand and collapse to reveal content. Each section can open on its own, unlike tabs.
The Header Is a Button
Make every accordion header a real button. Buttons are focusable, work with Enter and Space, and announce themselves to screen readers for free.
<button>Shipping details</button>A div Header Fails
Watch out for a clickable div as a header. It is not focusable, ignores the keyboard, and tells assistive tech nothing about its job.
<div onclick="toggle()">Shipping details</div>aria-expanded Is the Key
Add aria-expanded to the button so screen readers announce collapsed or expanded. This single state is what makes an accordion accessible.
<button aria-expanded="false">Shipping details</button>Toggle the State on Click
When the user activates the button, flip aria-expanded between true and false. Keep it in sync with whether the panel is actually showing.
btn.setAttribute("aria-expanded", String(open));Point at the Region
Use aria-controls on the button, set to the id of the panel it opens. Users learn which content this header reveals.
<button aria-controls="sec1" aria-expanded="false">More</button>Hide the Collapsed Panel
When a section is closed, give its panel the hidden attribute. That removes it from the page and from the accessibility tree until reopened.
<div id="sec1" hidden>Panel content</div>Wrap Headers in Real Headings
Place each button inside a real heading like h3. Screen reader users can then jump section to section using heading navigation.
<h3><button aria-expanded="false">FAQ</button></h3>No ARIA on Single Disclosures
A lone show-and-hide is a disclosure, not a tab set. It needs only a button with aria-expanded, no tablist or tab roles at all.
Keep Focus on the Button
After toggling, leave focus on the button the user pressed. Do not steal focus into the panel; that surprises keyboard users.
Why aria-expanded Wins
Because the button carries its own state, a screen reader says expanded or collapsed every time. Users always know what activating it will do.
Quick Check
You are building an accordion header that opens and closes a section. Which attribute makes its state accessible?
Recap: Accessible Accordions
You learned an accordion header is a button with aria-expanded, wrapped in a heading. Toggle the state, point at the panel, and hide it when closed.
Frequently asked questions
Is the “Accordions With Button and aria-expanded” lesson free?
Yes — the full text of “Accordions With Button and aria-expanded” is free to read here on the web, and the Web Accessibility Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Web Accessibility Academy course, upgrade to CoddyKit PRO.
What will I learn in “Accordions With Button and aria-expanded”?
Build a disclosure that announces open and closed. You practise Web Accessibility Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Web Accessibility Academy?
No prior experience is required. Web Accessibility Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Accordions With Button and aria-expanded” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Web Accessibility Academy lesson?
Yes. Every Web Accessibility Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- The Tabs Pattern: tablist, tab, tabpanel
- Arrow-Key Navigation Between Tabs
- Accordions With Button and aria-expanded
- Disclosure vs Tabs: Pick the Right One