...
The accordion component lets users show and hide sections of related content on a page, to simply simplify the interface where necessary.
...
A Table of Contents and sections with headings can equally allow a user to skip to the relevant subset of content for their needs, without hiding it visually.
Tabs also hide and reveal content, but cannot be used when the content within each tab needs to be compared, because only one tab panel is visible at a time.
A ‘subtle’ accordion is not only less visually prominent but should not be stacked into multiple draws. This may be better defined and separated as a disclosure widget, but is effectively a single accordion. The behaviour of accordions and disclosure widgets is also often seen in hamburger menu items and other ‘expand/collapse via button' interactions.
...
Accordion items are collapsed by default
Each accordion is individually controlled with a toggle between expanded and collapsed.
Each accordion includes hover, focus and disabled and active states. CSS ‘focus-visible’ will remove visual focus for mouse-controlled accordions.
Mouse click or touch on the accordion title will toggle between expand and collapse
Once focussed, Enter or Space on a keyboard will also toggle expand or collapse.
Once focussed, hitting tab or the down arrow moves to the next accordion title. The last title in the set loops back to the first. Note that clarity is needed between the WAI accordion example and the stacked disclosure example used for FAQs.
Once focussed, hitting shift+tab or the up arrow moves to the previous accordion title. The first title in the set loops back to the last.
When focussed anywhere on the accordion set, home moves focus to the first accordion title.
When focussed anywhere on the accordion set, end moves focus to the last accordion titleItems within an accordion ‘list’ can be traverse forwards with tab and backwards with shift+tab.
WAI also suggested the following best practices, but notes them as optional. This should be discussed in terms of effort vs impact.
Accordion items can also be traversed with up and down keyboard arrows.
Hitting home will move focus to the start, hitting end will move focus to the end of the list.
Hitting down on the last item or up on the first item will loop back around in a continuous loop.
Where Javascript is disabled, all accordions are expanded by default and expand/collapse controls are not present.
...
Ignoring the accordion and looking at the content within it semantically, it is likely that the markup would differ (per best practice) depending on what the content is. In some cases it might be a basic heading and paragraph, but for use cases like FAQs, these are often best delivered as definition lists <dl> with definition terms <dt> and definition descriptions <dd>. In other use cases still <summary> and <details> may be ore appropriate.
The control is a <button> which toggles aria-expanded between “true” and “false”.
Where the accordion item title is semantically a heading, it could be wrapped within <article> to section that content and aid programmatic determination of heading level. Headings are also a primary navigation pattern of screen-readers.
Where there is more than one accordion draw and it forms a list, nesting items with an unordered list will tell screen-readers how many items are in the accordion set. This is recommended in some live examples, but isn’t common (other than definition lists and FAQs) so can be tested.
The icon is deliberately placed before the title (left on LTR languages and right on RTL languages) to aid users of screen magnifiers, who may not be able to see the status if it was right aligned on a wide accordion. (Reminder that we should be using logical properties such as start/end rather than left/right wherever possible).
It is yet to be determined if aria-labels for accordion titles are needed. Editorial guidance suggests that the text should be reflective and clear as to the content within. A decision is needed whether to programmatically add them if a field was added to the content model and leave it to content modelling to decide, or confirm the content modelling and then adjust.
Research is being undertaken to determine whether there is a need for hidden text to give more context to unsighted users such as “expand the” [accordion title], etc. It may be that aria-expanded is enough.
Unexpanded Collapsed content should be visible to users or screen-readers. (e.g. display:none).
...
...
Examples
...
Useful links
...