Accordion

The scripting media query matches in modern browsers with JavaScript enabled in user settings even when JavaScript is otherwise blocked. To cover that case, add a <script> element to the HTML <head> that sets a class on the document root, then scope the CSS with a selector.

<!-- Add to <head> to condition availability of JavaScript -->
<script>document.documentElement.classList.add('js')</script>

@media (scripting: enabled) {
 :root.js {
   & .accordion-header > button {
     width: 100%;
     display: flex;
     justify-content: space-between;
     cursor: pointer;
   }
   & .accordion-header > button[aria-expanded]::after {
     display: block;
     content: "⌃" / "";
     transform: rotate(0.5turn);
   }
   & .accordion-header > button[aria-expanded="true"]::after {
     transform: rotate(0);
   }
   & .accordion-panel {
     display: none
   }
   & .accordion-panel.is-open {
     display: block
   }
 }
}

Reported as: Accordion has no disclosures

Each section of an accordion must be a disclosure whose control reports that it expands content and whether that content is showing.

When the sections expand and collapse only visually, with plain elements as controls and no aria-expanded anywhere, screen reader users hear the section titles and nothing else. They can't tell that a section holds hidden content, that its title is operable, or which sections they've already opened.

Give each control the button role and an aria-expanded attribute that tracks its panel. A <details> element with a <summary> meets this too, as Accordion Using Details and Summary shows. Even so, a section's heading belongs around a button rather than inside a <summary>.

For what aria-expanded has to do, see aria-expanded.

Severity: Serious

Reported as: Accordion breaks heading hierarchy

In an accordion whose sections need headings, each section's button should be wrapped in a heading, and should be the only thing inside it.

When a section's button has no heading around it, the section's title is missing from the page's outline, and screen reader users can't move between the sections by heading. When the heading also holds other elements, such as a badge or a menu button, assistive technology reports their content as part of the section's title, so screen reader users hear it every time they reach the section.

Wrap each button in a heading and move anything else beside it. For a section built from <details> and <summary>, rebuild it as a heading wrapping a button rather than adding a heading inside the <summary>.

Severity: Minor

Reported as: ARIA heading missing aria-level

A section heading built with role="heading" should declare its level with aria-level.

When the level is missing, the accordion's sections appear in the page's outline at a default depth nobody chose. Screen reader users who move through the page by heading get a structure that doesn't match how the content is organized.

Add aria-level set to the depth the sections sit at, one below the heading that introduces the accordion. Better, use a native heading element, which carries its level in the tag.

Severity: Moderate

Reported as: Accordion has mixed heading hierarchy

Every section heading in one accordion should use the same level.

When the levels differ, the outline tells screen reader users that some sections are subsections of others, although the sections are peers. The mistake is invisible on screen, where the headings usually look identical.

Choose the level once for the whole accordion, to fit where it sits in the page's outline, and apply it to every section from one place in your code. If a section's content nests, put the nested headings inside its panel rather than varying the levels of the sections.

Severity: Minor

Reported as: Element has incorrect role

A section's button must carry the button role.

When the element users operate in the heading has no role, or the wrong one, assistive technology reports the section's title as plain text or as some other kind of element. Screen reader users can't tell that the title opens anything.

Use an HTML <button> inside the heading, which carries the role on its own, or set role="button" on the element users operate.

Severity: Critical

Reported as: Incorrect root element

A section's button role should sit on the same element that receives focus and handles activation.

When the role sits on a descendant while a wrapper takes focus or handles the click, screen readers announce a button that isn't the element users operate, and keyboard users may reach a control that doesn't open the section.

Put the role, the accessible name, focusability, and the activation handling on that one element, and keep any wrapper free of roles and handlers. If the test selected a wrapper by mistake, select the section's button itself and run the test again.

Reported as: Accordion panel is not a section element

An accordion panel can be a named region, which makes it a landmark users can reach from the list of the page's landmarks.

When a panel holds substantial content, such as headings of its own or a nested accordion, a landmark lets users go straight to it. When a panel holds a few lines under its heading, a landmark only lengthens the list users have to read through.

Give the panel the region role only when its content earns one. Make it a <section> named by aria-labelledby pointing at its section's heading, and leave other panels without a role.

Severity: Minor

Reported as: Accessible name

A section's button must have an accessible name that says which section it reveals.

When the button holds only an icon, a chevron, or an image with empty alt text, the section's title sits beside it, outside the button, and users get a control they can operate and can't identify. Every section's button then exposes the same name, so choosing between them means opening each one to find out what it was.

Name the button from the text inside it. When the design leaves no visible text to use, fall back to meaningful alt text on a child image, an aria-label, or an aria-labelledby pointing at text elsewhere on the page.

Severity: Critical

Reported as: Summary has no accessible name

In a section built from a <details> element, the <summary> must contain text that says which section it reveals.

When the <summary> is empty, or holds only an icon or an image with empty alt text, users get a control they can operate and can't identify. Every section's summary then exposes the same name or none, so choosing between them means opening each one.

Put the text that names the section inside the <summary>. When the design leaves no visible text to use, give a child image meaningful alt text.

Severity: Critical

Reported as: Native disclosure is missing summary element

A section built from a native <details> element must have a <summary> element with an accessible name as its first child.

When the first child of the <details> element is the content itself, the browser still renders a control and falls back to a default string, usually "Details". Users get a stack of identically named controls and no way to tell which one holds what they came for.

Put a <summary> first inside each <details> element and give it the text that names the section. When the section needs a heading, build it as a heading wrapping a button instead.

Severity: Serious

Reported as: Disclosure panel has no accessible name

An accordion panel that carries a role should take its accessible name from its section's heading.

When a panel has a region or group role and no name, assistive technology reports it as a region with nothing attached, or as an unnamed group it may skip. Users who move into the panel, or who arrive at it by jumping between regions, are reading a section with no indication of which part of the accordion it belongs to.

Give each section's heading an id, and point the panel's aria-labelledby at it. Give a panel a role only when its content earns one, and don't put the attribute on a panel with no role, where it names nothing.

Severity: Minor

Reported as: Conflicting aria-expanded value

The aria-expanded value on a section's button must match whether its panel is showing: false while the panel is hidden and true while it's showing.

When the value is derived from something other than the panel's real state, it reports the opposite of what's on screen: users skip a section that's open in front of them, or go looking for content that was never revealed.

Set the attribute from the same state that decides whether the panel renders.

Severity: Critical

Reported as: Aria-expanded value did not change

The aria-expanded value on a section's button must change whenever its panel opens or closes.

When the panel changes and the value doesn't, the attribute goes on reporting the state the panel was in before, so screen reader users are told a section is closed while it's showing, or the reverse. In an accordion that closes other sections when one opens, the buttons of the closed sections need updating too.

Change the attribute in the same step that shows or hides the panel, whatever caused it to open or close.

Severity: Serious

Reported as: Missing aria-expanded attribute

A section's button must carry aria-expanded, in the collapsed state as well as the expanded one.

When the attribute is absent, nothing in the markup says the button reveals anything, so screen reader users have no reason to expect content to appear and can't tell afterward whether activating it worked.

Set it to false from the start rather than adding it once the panel has been opened.

Severity: Serious

Reported as: Component does not support disabled state

An accordion's disabled state must be set only on a section's button, never on its heading, its panel, or the accordion's container.

When disabled or aria-disabled is set on an element whose role has no disabled state, assistive technology may drop it or report the element as something it isn't, and the buttons inside stay fully operable. Nothing users can reach is actually disabled.

Take the attribute off the heading, panel, or container, and set it on the button of each section that is unavailable.

Severity: Serious

Reported as: Element type does not support disabled state

An element in an accordion must carry disabled or aria-disabled only when its role supports a disabled state.

When the state sits on an element whose role has none, such as a wrapper, a list item or a heading, assistive technology may drop it or report it on something users can't operate, while the control that really is unavailable is still reported as available.

Remove the attribute from that element, and set the disabled state on the control itself, using an element or role that supports it, such as a native <button>.

Severity: Serious

Reported as: Conflicting disabled values

A section's button must declare its disabled state one way only.

When the button carries the disabled attribute alongside an aria-disabled value that disagrees with it, assistive technology may report a different state than the browser enforces, so users can't tell whether the section will open.

Use disabled on a native <button> and aria-disabled on a button built from another element, never both.

Severity: Serious

Reported as: Element does not support the disabled attribute

A section's button built from an element that doesn't support the disabled attribute must convey its disabled state with aria-disabled.

When disabled is set on such an element, browsers ignore it, and the button stays an available control in the accessibility tree however grayed out it looks. Screen reader users are told they can open a section the design means to be unavailable.

Set aria-disabled="true" instead, and keep it in step with the code that stops the button from toggling its panel. A native <button> avoids the problem, since disabled then does all of it.

Severity: Serious

Reported as: Forbidden interactive children; Nested interactive elements

A section's button must not contain or be nested inside another interactive element, such as a link or another button.

A button has no accessible children. An interactive element nested inside it is presentational, so screen reader users can't perceive or operate it as a control.

Move the interactive element out of the button. A control for actions on the section, such as a menu button, goes beside the heading rather than inside it.

Severity: Serious

Reported as: Aria-controls has multiple targets

A section's button should name only its own panel in aria-controls.

When the attribute lists several ids, such as every panel in an accordion where opening one section closes the others, the button no longer says which content it shows. Assistive technology that offers to move users to the controlled element has to pick one or offer none.

Point each button's aria-controls at its own panel. Closing the other sections is a side effect of opening this one, not something the button controls.

Severity: Minor

Reported as: Invalid aria-controls reference

A section's button must point aria-controls at a panel that exists on the page.

When the id matches nothing, because it's misspelled or names a panel that hasn't been rendered, assistive technology finds no target and can't tell users what the button affects, while the markup still looks correct.

Generate each panel's id and its button's aria-controls value from the same source. When a panel exists only while it's open, add the attribute when the panel appears and remove it when the panel goes.

Severity: Minor

Reported as: Missing aria-controls attribute

A section's button should name its panel with aria-controls.

When nothing connects the button to its panel, the relationship exists only in the layout and the script. Assistive technology that uses the attribute can't tell users which content the button shows, or offer to move them to it.

Give each panel a unique id, and set its button's aria-controls to that id.

Severity: Minor

Reported as: Avoid aria-owns

An accordion and its sections' buttons should not use aria-owns.

The headings and panels already sit inside the container in reading order. When an accordion or a section's button owns them anyway, assistive technology can present a panel away from its heading, and screen reader users meet content with no indication of which section it belongs to.

Remove aria-owns and keep each heading and its panel in the container, in order. A section's button names its panel with aria-controls, not aria-owns.

Reported as: Invalid aria-owns values

When an accordion or a section's button uses aria-owns anyway, each element it references should have a role its owner accepts.

An accordion's container has no role, so no owned element has a role it can accept, and a section's button treats everything inside it as presentational. When either claims headings, panels or other buttons, assistive technology can drop them or present them out of place, and screen reader users lose track of which panel belongs to which heading.

Remove aria-owns, and keep each heading and its panel inside the container in reading order, as the section intro describes.

Reported as: Keyboard accessible

A section's button must be reachable with the Tab key.

When the button is built from markup that isn't focusable, such as a <div> or a <span> given click handling and a role, keyboard users can't reach it, so the section it reveals is out of their reach too.

Use a <button> element, which is focusable on its own, or a <summary> in a section built from <details>. When the button has to stay generic, add tabindex="0" so it joins the tab order in document order.

Severity: Critical

Reported as: Disabled element focusable

A section's button that presents as disabled should not be a stop in the tab order.

When Tab still lands on a disabled button, because a native <button> was styled as disabled without the disabled attribute or a generic one kept tabindex="0", keyboard users arrive at a button that reveals nothing.

Use the disabled attribute on a native <button>, which removes it from the tab order. On a generic button, set tabindex="-1" while it's disabled and restore tabindex="0" when it's available again. If you keep it focusable so users can hear why it's unavailable, make sure assistive technology reports the disabled state and activation is blocked.

Severity: Minor

Reported as: Focusable offset

The element that carries a section's button role must be the element that receives focus, not one of its descendants.

When the role sits on a wrapper and focus lands on a child inside it, screen reader users tabbing through the accordion hear nothing about what they've landed on, and can't tell it's a button that reveals a section.

Make the element with the role focusable, with a <button> element or tabindex="0", and remove focusability from the descendant that was taking focus.

Severity: Minor

Reported as: Button not activated by keyboard

A section's button must show and hide its panel when keyboard users activate it.

When a button built from a generic element handles only the click event, keyboard users can focus it but can't open the section.

Use a native <button> element, which is keyboard operable on its own. Otherwise, add keyboard event listeners that either toggle the panel or create a click event that does.

Severity: Critical

Reported as: Disabled button keyboard activation

A section's button that reports itself as disabled should reject keyboard activation.

When a button carries aria-disabled="true" but the Enter or Space key still toggles its panel, screen reader users may be confused or lose trust in the interface.

Use a native <button>, which blocks interaction when disabled is set. Otherwise, check the disabled state in the keyboard handlers and return before toggling anything.

Severity: Serious

Reported as: Button requires space key activation

A section's button must activate with the Space key as well as the Enter key, as a <button> element does.

When only Enter works, users who press Space, as they would on any other button, may conclude the button is unresponsive.

Add a Space keyup handler that toggles the panel, or use a native <button> element.

Severity: Minor

Reported as: Element's state did not change

A section's button must update aria-expanded every time it's operated.

Nothing looks broken to sighted users, who watch the panel open and close, while screen reader users are told it's still in the state it started in. After a few presses with no change in what they hear, they decide the button is broken.

Derive the attribute from the same state that decides whether the panel shows, and handle pointer and keyboard activation through one path rather than two.

Evinced reports this issue as Critical or as Serious, depending on the context where it shows up.

Severity: Critical

Reported as: Toggle state not resetting

Activating a section's button twice must return aria-expanded to the value it started with.

When the code assigns a fixed value on activation instead of inverting the current one, the attribute stops tracking the panel after the first press. The panel goes on opening and closing, and screen reader users are told a closed section is open.

Invert the state on each activation rather than assigning a fixed value.

Evinced reports this issue as Critical or as Serious, depending on the context where it shows up.

Severity: Critical

Reported as: Invalid toggle attribute

When a section built from a <details> element carries aria-expanded on the <details> or the <summary> element (not recommended), the value must stay consistent with the open attribute.

The browser derives the state from open while assistive technology reports the ARIA value to users, so the two disagree from the first toggle. Nothing in the native construction updates the attribute, so screen reader users go on being told that a section they've just opened is closed.

Remove aria-expanded and let the native state stand. When it can't be removed yet, update it from the toggle event on each <details> element so it at least tracks open.

Severity: Serious

Reported as: Disabled element active

A section's button that presents as disabled must not toggle its panel when it's activated.

aria-disabled="true" changes only what's reported, not what the browser allows, so the click and key handlers keep firing unless the code checks the state itself. Users are told the section isn't available and then find that it opens, and they can't tell whether they've broken something they were warned off.

Check the disabled state at the top of the handler and return before changing anything, covering the pointer and the keyboard paths. On a native button, use the disabled attribute, which stops activation in the browser.

Severity: Moderate

Reported as: Unresponsive disclosure button

Activating an expanded section's button again must collapse its panel.

When the second activation does nothing, the panel stays open and the button gives no response. Users can't put the section away, and a button that works once and then stops reads as broken.

Handle every activation as a toggle: expand the panel when it's collapsed and collapse it when it's expanded, updating aria-expanded each time.

Severity: Minor

Reported as: Accordion panel does not close

Users should be able to collapse an expanded panel without expanding another, unless the accordion is designed to keep one panel open.

When a panel collapses only as another one opens, users can't return the accordion to its headings, and screen reader users hear a section stay open after they tried to close it.

Let a second activation of the same button collapse its panel. If the accordion is meant to keep one panel open, say so in visible instructions, and keep aria-expanded accurate on every button.

Severity: Minor

Reported as: Deprecated keypress listener

An accordion's key handling should use keydown or keyup, not keypress.

When a handler listens for keypress, keys the browser doesn't send through that event go unanswered, and keyboard users find the accordion ignoring keys it's meant to respond to.

Replace each keypress listener with a keydown listener, and read the key from event.key.

Severity: Minor

Most accordion issues relate to 4.1.2 Name, Role, Value: a section's button with the button role and an accessible name, a <summary> first in each <details> element, sections that are valid disclosures, a disabled state set on the button and declared one way only, no interactive elements inside the button, a state that updates when the button is operated and stays consistent with open on a native section, and a button that collapses its panel when it's pressed again.

Under 1.3.1 Info and Relationships, each button's aria-expanded reflects whether its panel is showing, aria-controls is present and points at the panel, and a disabled button ignores activation. Under 2.1.1 Keyboard, each button can be reached with the Tab key, takes focus itself, and activates with Enter and Space.

The rest are best practices that map to no success criterion: giving ARIA headings a level, keeping heading levels consistent, wrapping each section's button in a heading, giving panels a region role only when their content earns a landmark, naming each panel from its heading, pointing aria-controls at a single panel, and keeping a disabled button out of the tab order and away from keyboard activation.

Severity reflects how much an issue gets in users' way. Critical issues stop users outright: a section's button without the button role or a name, a section that can't be reached or opened by keyboard, or an aria-expanded value that's wrong or doesn't change when the button is operated.

Serious issues break the accordion for assistive technology users: a section that isn't a valid disclosure, a button with no aria-expanded or one whose value stays put when the panel opens or closes, a <details> element with no <summary>, a disabled state reported wrongly, an interactive element nested in a button, a stale aria-expanded on a native section, or a disabled button that still responds to the keyboard.

Moderate issues weaken navigation or trust, such as an ARIA heading with no level or a disabled button that still opens its section. Minor issues affect how easily users find their way, such as inconsistent heading levels, buttons without headings, panel roles and names, aria-controls that's missing or wrong, a disabled button left in the tab order, focus that lands inside a button, or a button that ignores the Space key.

Two checks carry no severity: the general check for aria-owns and the sanity check on where the button role sits.