HubSpot module documentation
Accessible FAQ Accordion
An FAQ accordion that a keyboard and a screen reader can both drive. Each question is a real button, the open state is announced rather than implied, and the focus outline is yours to colour.
Why this one rather than any accordion
Most accordions are a styled div that listens for a click. That works with a mouse
and fails with everything else. This one is built the other way round.
- Every question is a
button, so it is reachable by Tab and operable by Enter and Space without any extra code. - The open and closed state is carried in
aria-expanded, so a screen reader says whether the answer is showing instead of leaving the listener to guess. - The answer is tied to its question with
aria-controls, so assistive technology knows which panel belongs to which button. - The focus outline is a field, not something to be removed. Set it to a colour that shows against your background.
The European Accessibility Act has applied since June 2025, so for many companies selling into the EU this is a compliance question rather than a preference.
Set up the content
Under Content in the Content tab.
| Field | What it does |
|---|---|
| Heading | The heading above the list. Leave it empty if the surrounding page already has one. |
| Heading level | The level written into the page, h1 through h6. Match it to where the block sits in the page outline, not to how large you want the text. |
| Accessible name for the list | What a screen reader announces when it reaches the accordion. "Frequently asked questions" is usually right. It is read instead of the visible heading, so make it say what the list is. |
| Questions | A repeating group. One row per question, each with a Question and an Answer. |
Expand and collapse
- Show expand / collapse all adds a control above the list. On by default.
- Expand all label and Collapse all label are the wording on it, so it can be translated without touching the module.
Style it
Every colour lives in the Styles tab, grouped by what it affects.
| Group | Controls |
|---|---|
| Text | Question and answer colours. Both inherit your theme's primary and secondary colours until you change them. |
| Background | Behind the question row and behind the answer. |
| Border | The rule between rows. |
| Hover | Question text, question background and border, while the cursor is over a row. |
| Open question | Question text and background once the answer is showing, so the open row is visibly different. |
| Arrow | The indicator colour at rest, on hover, and when open. |
| Shadow | On by default, with its own colour. Turn it off for a flat look. |
| Focus indicator | The outline drawn when a question is reached by keyboard. Check it against your background; this is the control that decides whether someone tabbing through can see where they are. |
Check it before you publish
- Press Tab until focus reaches the first question. You should see the focus outline clearly.
- Press Enter or Space. The answer opens and the arrow changes.
- Tab onward. Focus moves to the next question, not into hidden content.
- If you use a screen reader, confirm it says "expanded" or "collapsed" as you move.
If the focus outline is hard to see, raise the contrast of Focus indicator, Colour. That is the single most common finding in an accessibility audit of an accordion.
Support
Email support@freelopers.com. We answer in English, Monday to Friday, 10:00 to 17:30 CET.
Please include the page URL, your browser and device, and the steps that reproduce the problem. Please do not send passwords or API keys.