Disclosures and accordions show up all over the place—FAQs, menus, settings panels—you name it. They seem simple enough, right? But making sure they actually work for everyone takes more than just toggling some content and calling it a day.
If you’ve ever wondered when to use <details> versus building an accordion with buttons and ARIA, or how to keep screen reader users from getting lost in a sea of hidden panels, you’re not alone. This guide breaks it all down—what to use, when to use it, and how to build a truly accessible accordion without overcomplicating the code.
What Are Disclosure and Accordion Widgets?
Disclosure Widgets: Simple, Native, and Often Overlooked
Disclosures—also known as show/hide widgets—are ideal for toggling a single section of content. Think expandable FAQs or inline help that doesn’t clutter the UI by default.
Here’s a basic example using semantic HTML:
<details>
<summary>Need more info?</summary>
<p>Here are more details you might find useful.</p>
</details>This pattern is fully native and built into the browser, which means it comes with keyboard support and screen reader compatibility right out of the box. You also get the open attribute, which allows you to control whether the content is expanded by default.
The main advantage here is simplicity—no JavaScript needed, and fewer chances to introduce accessibility issues.
Accordion Widgets: More Complex, More Control
An accessible accordion expands on the idea of disclosure by managing multiple content panels. In most implementations, only one section is open at a time, helping users stay focused and reducing cognitive overload.
You can build an accordion using multiple <details> elements, but if you want to control behavior more precisely—like closing other panels when one opens—you’ll need JavaScript.
Here’s what a minimal HTML-only version might look like:
<details name="accordion">
<summary>Step 1</summary>
<p>Instructions for step one.</p>
</details>But to meet WCAG standards for a true accessible accordion, you’ll need to manage keyboard navigation, state indicators, and focus behavior—topics we’ll cover next.
Accessibility Considerations Developers Must Prioritize
Keyboard Navigation That Works for Everyone
An accessible accordion must support meaningful keyboard interactions. Here’s what users expect:
TabandShift + Tabto move between interactive elements.EnterorSpaceto toggle a section open or closed.Arrow Up/DownorHome/Endto move between accordion headers in more advanced versions.
Missing any of these can make your component unusable for keyboard users. The WAI-ARIA Authoring Practices offer detailed guidance on accordion interaction patterns—worth bookmarking for reference.
Use Semantic Elements—Always
If there’s one golden rule, it’s this: never sacrifice semantics for styling.
That means:
- Use
<button>for interactive triggers—not<div>,<span>, or anchor tags without href. - If you’re toggling visibility, it’s a button, not a link.
- Ensure that elements behave as users (and assistive technologies) expect.
Using semantic elements is one of the most effective ways to ensure your accessible accordion behaves predictably across screen readers and input types.
Add ARIA Where Needed, Not Everywhere
ARIA should enhance native HTML—not replace it. But when you’re building a custom accordion in JavaScript, ARIA becomes essential for communicating component state.
Here’s a basic implementation:
<button aria-expanded="false" aria-controls="info">More Info</button>
<div id="info" hidden>
<p>Here’s the additional info.</p>
</div>
const btn = document.querySelector('button');
const content = document.getElementById('info');
btn.addEventListener('click', () => {
const expanded = btn.getAttribute('aria-expanded') === 'true';
btn.setAttribute('aria-expanded', String(!expanded));
content.hidden = expanded;
});This ensures screen readers can track whether content is visible or hidden, creating a seamless experience for all users.
Common Accessibility Mistakes (and How to Fix Them)
Even seasoned devs slip up. Here are a few common issues that can break accessibility—and how to address them:
| Mistake | Problem | Solution |
| Non-focusable triggers | <div>s with onclick don’t work for keyboard users | Use <button> or add tabindex="0" |
| Links used instead of buttons | <a> without href doesn’t convey intent | Replace with semantic <button> |
| Missing state feedback | Screen readers can’t detect if content is expanded | Dynamically update aria-expanded |
| Focusable elements in hidden content | Users tab into content they can’t see | Use hidden or display: none correctly |
Most of these issues stem from skipping semantic HTML or relying too heavily on JavaScript without proper state management. An accessible accordion avoids these pitfalls by focusing on clarity, intent, and interaction feedback.
Best Practices for Developers
Building an accessible accordion that holds up in the real world means going beyond code snippets. Here’s what to keep in mind:
Start with Progressive Enhancement
Whenever possible, begin with HTML <details> and <summary>. They’re accessible by default and supported in all major browsers. Use JavaScript only when additional behavior—like limiting panels to one open at a time—is truly needed.
Prioritize Focus Visibility
An accordion is only as accessible as its focus states. Make sure every interactive element has a visible focus indicator, and don’t override :focus-visible in your CSS. This isn’t just a WCAG 2.2 requirement—it’s also just good UX.
Avoid Overengineering with ARIA
Don’t reach for ARIA unless you need to. Native HTML tends to be more robust across assistive technologies, and using ARIA incorrectly can make things worse. When in doubt, simplify.
Test Like a User
If you’re not testing with a keyboard, you’re flying blind. Add screen reader testing with NVDA, JAWS, or VoiceOver into your QA flow. Run Lighthouse and WAVE scans, but don’t rely on them alone—they won’t catch everything an actual user would encounter.
Real-World Application: From Good to Great
Let’s say you’re rebuilding a legacy FAQ section. It uses JavaScript to toggle open answers, but it’s riddled with <div>s and missing ARIA.
Start by replacing the markup with semantic HTML:
<details>
<summary>What’s your return policy?</summary>
<p>You can return items within 30 days.</p>
</details>Then, enhance with JavaScript if you want only one section open at a time. Layer in ARIA attributes to improve screen reader support. Suddenly, you’ve turned a clunky widget into a polished, accessible accordion that works for everyone.
Wrapping It Up
Disclosures and accordions might seem interchangeable, but the differences matter—especially when accessibility is on the line. Whether you’re working on a quick FAQ or building a fully dynamic interface, an accessible accordion ensures users with different abilities can navigate and interact with your content.
At the end of the day, accessibility isn’t about checking boxes—it’s about building better interfaces for everyone.
Need help auditing your components?
216digital offers in-depth accessibility support. Schedule an ADA compliance consultation to review your current implementation and ensure everything meets WCAG standards—without compromising design or performance.