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.
Answer engines
A question with its answer is exactly the shape an answer engine looks for. This module publishes
yours as schema.org FAQPage data alongside the visible accordion, so the content a visitor
reads is also available to a machine in a form it does not have to infer from your markup.
| Field | What it does |
|---|---|
| Add FAQPage structured data | Under Answer engines in the
Content tab. On by default. Turn it off only when another module on the same page already
publishes FAQPage data, because a page should carry one such block, not two. |
Two things are worth knowing. Answers are published as plain text, so formatting and links inside an answer are stripped from the data and left untouched in the visible panel. And Google stopped showing FAQ rich results for every site on 7 May 2026, after limiting them to government and health sites in 2023, so this is not a route to a larger search listing. It is here so that a machine reading your page gets your questions and answers as data, in your wording, instead of guessing at them.
To check it on a published page, view source and search for application/ld+json, then paste
the block into any schema validator.
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.