Accordion
Questions and answers that open in place. Built on the browser's own details element, so it works with a keyboard, a screen reader and no JavaScript.
How fast can you turn around a prototype?
A Prototype Sprint delivers a working, testable prototype in 2–3 weeks, scoped up front.
Is accessibility included?
Built in, not bolted on: WCAG 2.2 AA from the first prototype.
How fast can you turn around a prototype?
A Prototype Sprint delivers a working, testable prototype in 2–3 weeks, scoped up front.
Is accessibility included?
Built in, not bolted on: WCAG 2.2 AA from the first prototype.
Show code
---
import Accordion from '@somnia/core/components/Accordion.astro';
---
<Accordion items={[
{ q: 'How fast can you turn around a prototype?', a: 'In 2–3 weeks…' },
{ q: 'Is accessibility included?', a: 'Built in, not bolted on…' },
]} /> When to use it
- Detail that only some people want: questions and answers, terms, a long specification.
- Whole sections of a long page that someone will open one or two of.
Use something else when:
- Everyone needs it: leave it open on the page.
- It is a few more lines of the same text: Read more. The rest of a list: See more.
- The parts are alternatives to switch between: a segmented control.
How it works
- Each item opens and closes on its own; opening one never closes another. Only the first starts open.
- Space or Enter toggles an item; the chevron turns and takes the accent colour when open.
- Answers are always in the page, so the FAQ structured data matches what people can read.
- An answer that needs a link takes an
htmlversion alongside the plaina: the page shows the html, and the structured data keeps the plain text. - In print every item is printed open.
One item, any content
AccordionItem is a single item with any content: a heading or text in its title slot (or a title prop) and anything in the body. The accordion above is built from it. Give it remember (a key) and it stays open or closed as the visitor left it, for the browser tab. The Media library on staging sites folds each group of photos and videos this way.
Do and don't
Do
- Use it for genuinely optional detail, like FAQs
- Write the summary as the question a visitor would ask
Don't
- Hide information everyone needs inside a closed item
- Nest accordions
Accessibility
What it does for you
- The browser’s own
detailsandsummary: the keyboard, the open or closed state and "no script" all come from the element. - Each question opens and closes by itself; opening one never shuts another.
- The whole summary is the target, 64px high. The chevron is decoration.
- A closed answer is still in the page, so the structured data matches what a person can open and read.
- Everything is printed opened. With reduced motion the chevron turns at once.
What you need to do
- Write the summary as the question someone would ask.
- Nothing everyone needs goes inside a closed item.
- When an item folds a whole section, give it the heading level the page’s outline needs.
Keyboard
| Key | What it does |
|---|---|
| Tab | Moves to each question. |
| Enter or Space | Opens or closes it. |
What a screen reader is told
- Each question by its words, with whether it is collapsed or expanded.
- When open, its answer follows as ordinary text.
This is what the browser reports to assistive technology. What each screen reader then says varies, and has not been listened to yet.
WCAG 2.2
| Criterion | Level | How this meets it |
|---|---|---|
| 2.1.1 Keyboard | A | A native element: Enter and Space both work. |
| 2.3.3 Animation from Interactions | AAA | The chevron’s turn switches off with reduced motion. |
| 2.4.7 Focus Visible | AA | A 2px ring inside the item’s edge. |
| 2.5.8 Target Size (Minimum) | AA | The summary is 64px high. |
| 4.1.2 Name, Role, Value | A | Open or closed is the element’s own state. |
The criteria this component has a part in. A page that uses it still has to meet the rest.
Checked
| Check | How | Result |
|---|---|---|
| Automated (axe-core) | WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in dark | Passed Nothing found, light or dark |
| Narrow screen | No sideways scrolling at 320px wide (WCAG 1.4.10) | Passed No sideways scrolling |
| Keyboard and what the browser reports | Real key presses on the live example, and the role, name and state given to assistive technology | Passed 8 of 8 checks pass |
| On paper | Somnia’s print check: no overlaps, stranded headings or controls on the page | Passed No faults on 5 sheets |
| Screen reader | Listened to by a person, in VoiceOver and NVDA | Not yet Not yet checked by a person |
The 8 checks made with the keyboard, on the example at the top of this page:
- Passed Tab reaches each question, in order
- Passed Enter opens a question and Space closes it
- Passed Opening one leaves the others as they were
- Passed Each is the browser’s own details element, its summary first, with no roles added
- Passed A closed answer is still in the page
- Passed Keyboard focus shows a 2px ring on the question
- Passed Each question is at least 44px high
- Passed With reduced motion the chevron turns at once
Run by script on against Somnia DS 1.89.0, in Chromium with axe-core 4.14.0. How these checks work, and every component's results.
Not yet checked
- How it sounds in a screen reader (VoiceOver, NVDA, TalkBack) has not been checked by a person. The roles, names and states the browser reports are checked by script; what is actually spoken is not.
- Windows high contrast (forced colours) has not been looked at by a person.
- When an item folds a whole section, its heading sits inside the summary. Some screen readers leave such a heading out of their list of headings. Not checked.
- Whether a browser’s find-in-page opens a closed item differs between browsers and has not been tried in each.
Evidence
Where it's used
| Where | For |
|---|---|
| mediadreams.co.uk | Questions on Services and on the Somnia CMS page. |
| Headland Yachting | Questions on the home page; every section of a yacht page folds; the availability calendar’s later months. |
| Staging sites | The Media library folds each group of photos and videos. |
What we saw, and what changed
| When | What we saw | What changed |
|---|---|---|
| An answer that needed a link couldn’t have one: answers were plain text, for the structured data. | An answer can carry an HTML version beside the plain one (1.8.0). | |
| The accordion took questions and answers only. | AccordionItem: one item with any content, which can stay as the visitor left it for the tab (1.22.0). | |
| A long page needed whole sections folded away, each still a heading. | An item can be a section: its title is the section’s heading, between two rules, not in a card (1.37.0). | |
| A link to a section that was shut, or to something inside one, landed on a closed heading. | The section opens first (1.38.0). |
From building and using it on real sites, each entry taken from the changelog or the build's own notes. This is observation by the studio and its clients, not research sessions with users.
What it rests on
- ARIA Authoring Practices: Disclosure: A button that shows and hides a region and says which state it is in.
What we don't know yet
- Which questions people open is not counted.