Accordion

Search…
Accordion
A series of expanding/collapsing panels of content.
Allows vertical stacking of content panels. Each panel is separated by an interactive panel header. Zero or more panels can be open at any time.
Often used in sidebars and navigation menus for the progressive disclosure of links and filters.
The accordion pattern is a composite pattern; each item in the accordion is a details disclosure widget.
Updated: Nov 29th, 2021 (removed Internet Explorer guidance).
Working Examples
You can take a look at the accordion pattern in action on our examples site.
You can get an idea of the required markup structure by viewing our bones site.
Terminology
We use the following terminology when discussing this pattern.
accordion: the pattern as a whole, comprised of the following sub-parts
panel: each panel in the accordion is a details disclosure widget
header: each panel displays an interactive summary of the panel contents
heading: each header contains a nested heading level element
auto-collapse: an accordion that automatically collapses other open panels when a new panel is opened
Best Practices
Each header will be in the natural tabindex, courtesy of the details pattern. This natural tabindex must not be removed or tampered with.
By default, all panels can be in an open, expanded state.
Optionally, the accordion may be restricted to only show one content panel at a time (i.e. opening a panel will close any other open panel). This is known as an auto-collapsing accordion.
Interaction Design
This section provides detailed instructions for how different input types should navigate and operate the pattern.
Keyboard
Pressing TAB key must move keyboard focus from one header to the next. It will also move focus through any interactive elements inside open panels.
Likewise, pressing SHIFT-TAB keys moves focus backwards through headers and interactive panel content.
Pressing SPACEBAR or ENTER key on a header with keyboard focus must open the panel. For auto-collapse accordions, any other open panel must close.
Screen Reader
Virtual cursor must be able to move from one header to the next.
With virtual cursor on header, it must be able to open panel via click event simulation. For auto-collapse accordions, any other open panel must close, but this should not be announced.
Pointer
Tapping or clicking a header must open the related content panel. For auto-collapse accordions, any other open panel must close.
Developer Guide
The accordion pattern makes heavy use of the HTML details tag. Older browsers, including IE11 and Edge, do not support the details tag natively, and so require a polyfill. 
HTML 
The structure is a list of details widgets. Note that in some browsers the implicit list role is removed when CSS 'list-style-type: none` is applied, an s 
<ul class="accordion" role="list" aria-roledescription="accordion">
    <li>
        <details class="accordion__details" open>
            <summary><h4>Buying</h4></summary>
            <ul>
                <li><a href="http://www.ebay.com">Purchases</a></li>
                <li><a href="http://www.ebay.com">Bids/Offers</a></li>
                <li><a href="http://www.ebay.com">Didn't Win</a></li>
            </ul>
        </details>
    </li>
    <li>
        <details class="accordion__details">
            <summary><h4>Selling</h4></summary>
            <ul>
                <li><a href="http://www.ebay.com">Sold</a></li>
                <li><a href="http://www.ebay.com">Bids/Offers</a></li>
                <li><a href="http://www.ebay.com">Didn't Swell</a></li>
            </ul>
        </details>
    </li>
</ul>
Note that in some browers the implicit list role is removed when CSS list-style-type: none is applied, and so we have applied role=list in our markup to ensure the role is explicit.
CSS
Other than the issue of list semantics mentioned above, there are no concerns with relation to CSS and accessibility. You may style your accordion headers and panels however you please.
JavaScript
For accordions that allow all panels to be open at once, no scripting is necessary; each nested details widget will handle the open and close mechanics.
For accordions that are restricted to a single open panel, the JavaScript steps can be briefly summarised as the following:
1.Find each nested details element
2.Listen to toggle event of each details element
3.When receiving a toggle event, if the details state has moved from closed to open, close all other details elements
That's it. Pretty straightforward. You can reference our example code on GitHub.
ARIA Reference
aria-roledescription: defines a human-readable, author-localized description for the role of an element. In this case, "accordion".
Disclosure
Carousel
Last modified 18d ago
Copy link
On this page
Working Examples
Terminology
Best Practices
Interaction Design
Developer Guide
ARIA Reference