Skip to main content
Accessibility Field Guide

Accordions

A practical Accessibility Field Guide page for checking expandable accordion sections, disclosure buttons, headings, keyboard support, focus, and expanded state.

Rows of gray metal file cabinet drawers with books lined along the top.
Photo: Gray Steel File Cabinet via Pexels — https://www.pexels.com/photo/gray-steel-file-cabinet-1370294/
View full screen Download image

An accordion is a set of sections that can expand and collapse.

That sounds simple, but accordions can hide a lot of accessibility problems if the team only checks whether the panel opens with a mouse.

A useful accordion needs to make the section title clear, expose whether the section is open or closed, keep keyboard behavior predictable, and avoid hiding information people need to complete the task.

The goal is not to make every block of content collapsible.

The goal is to use accordions when they help the page stay understandable, and to make the expanded and collapsed state real for everyone.

The common project moment

A page starts to feel long.

There are several sections of instructions, details, policy notes, form groups, filters, frequently asked questions, or optional settings. Someone suggests an accordion because it makes the screen look cleaner.

In the design file, the pattern feels tidy:

  • each section has a short title;
  • only the selected section is open;
  • the closed sections take up less space;
  • a chevron points up or down;
  • the page looks less overwhelming.

But the implementation may tell a different story:

  • the header is a clickable div instead of a button;
  • the section title is not exposed as a heading or useful control name;
  • the chevron changes visually, but aria-expanded does not update;
  • keyboard users can tab to the header but cannot activate it with expected keys;
  • focus moves into hidden content or skips newly opened content in a confusing way;
  • required instructions are hidden in a collapsed panel;
  • the accordion is being used to make a confusing page look shorter instead of making the task clearer.

That is where accordion problems usually start.

The visual design says, "open this section when you need it."

The code needs to say the same thing.

Start by asking whether the content should be hidden

Before checking ARIA, ask whether the accordion is helping the task.

Accordions can be useful when people need to scan several related sections and open the one they need.

They are riskier when they hide content people must read before making a decision.

Use caution when an accordion hides:

  • required form instructions;
  • error recovery steps;
  • eligibility or policy details that change the user's choice;
  • warnings or consequences;
  • controls needed to complete the current step;
  • information that most users need every time.

If the content is essential, the better fix may be clearer page structure instead of a collapsible pattern.

Make the header a real control

Each accordion header should have a control people can operate.

In most cases, that means a real <button> inside a heading.

The heading gives the section a place in the page structure. The button gives the user something interactive to focus and activate.

Avoid making the whole heading, row, icon, or div clickable without a real control behind it.

A good accordion header answers three questions:

  • What section is this?
  • Can I open or close it?
  • Is it open right now?

If the visible title is "Payment details," the accessible name should not be only "expand" or "chevron."

The control should be named from the section title, not from the icon.

Expose expanded and collapsed state

An accordion's visual state needs to match its programmatic state.

When a panel is open, the header control should expose that it is expanded.

When the panel is closed, the header control should expose that it is collapsed.

That usually means updating aria-expanded on the button when the section changes.

If aria-controls is used, it should point to the real panel that the button controls.

Do not set ARIA once and forget it.

The state needs to change when the user opens or closes the panel.

Keep keyboard behavior predictable

At minimum, each accordion header button should be reachable with Tab and operable with Enter and Space.

That baseline matters more than adding complex keyboard shortcuts.

Some accordion patterns also support arrow-key movement between headers. That can be helpful when the accordion is treated like a composite widget, but it should not replace normal tab access.

Check the simple path first:

  • Can a keyboard user reach each accordion header?
  • Does the visible focus indicator show where they are?
  • Can they open and close each section without a mouse?
  • Does focus stay on the header unless the interaction has a clear reason to move it?
  • Does the page avoid trapping focus inside collapsed or hidden content?

If the accordion contains form fields or links, those items should only be in the tab order when the panel is visible.

Do not rely on the chevron

A chevron can help sighted users notice whether a section is open or closed.

It should not carry the whole meaning.

People should be able to understand the accordion from the section title, button role, and expanded or collapsed state.

If the only difference is an icon rotation, the state may be easy to miss.

That matters for people using assistive technology, people with low vision, people using magnification, and anyone moving quickly through a dense page.

Use the chevron as a visual cue, not as the only cue.

Watch for accordions inside forms

Accordions inside forms need extra care.

A collapsed section can hide required fields, validation messages, instructions, or the next action.

If a user submits a form and an error is inside a closed accordion panel, the page needs to help them find it.

That may mean:

  • opening the section that contains the error;
  • moving focus to a useful place;
  • identifying which section needs attention;
  • keeping the error message tied to the field;
  • avoiding a summary that points to content that remains hidden.

A form accordion should make the process easier, not turn the form into a scavenger hunt.

Questions teams can ask

During design

  • Is this content optional, or does the user need it to complete the task?
  • Is an accordion making the page easier to understand, or just shorter?
  • Are the section titles specific enough to scan?
  • What visual cue shows whether each section is open or closed?
  • What should happen when a section contains an error?

During development

  • Is each header a real button?
  • Is the button named from the visible section title?
  • Does aria-expanded update when the panel opens or closes?
  • Does aria-controls, if used, point to the correct panel?
  • Are hidden panel contents removed from the keyboard path?
  • Can the accordion be operated with Tab, Enter, and Space?

During QA or internal review

  • Can I open and close every section without a mouse?
  • Can I tell which section is open right now?
  • Does focus remain visible and predictable?
  • Are important instructions or errors hidden in closed sections?
  • Does the accordion still make sense when more than one section is open, if that is allowed?

Common trail hazards

  • Using a clickable heading or div instead of a button.
  • Naming the control "expand" instead of using the section title.
  • Rotating a chevron while leaving aria-expanded unchanged.
  • Hiding required instructions inside a collapsed panel.
  • Letting keyboard focus move into content that is visually collapsed.
  • Closing a panel while focus is still inside it.
  • Using an accordion because the page is too long instead of improving the content structure.
  • Assuming a component library's accordion is accessible without checking the rendered HTML and behavior.

Small habit

When reviewing an accordion, test one section with this sentence:

This is a button for [section title]. It is currently [expanded or collapsed]. I can open or close it with the keyboard, and the panel content follows the same state.

If that sentence is not true, fix the behavior before adding more panels.

What to do next

Use this page on one accordion before copying the pattern to more screens.

Start with the plain behavior: real button, clear section title, visible focus, keyboard activation, and accurate expanded or collapsed state.

Then use ARIA to describe that behavior, not to cover for behavior that is missing.