FAQ accordion

1. Copy to Webflow

   Add Geist and Geist Mono to your site's fonts (Site settings, Fonts, Google Fonts) before pasting: Webflow removes any font your site has not installed.
   Copy to Webflow

2. Add custom CSS

   To keep things simple, the code ships inside the Webflow embed. You can also copy it here and add it yourself to the page or site custom code. How to choose

   The look of the preview is the faq-* classes of the paste. The Embed holds what moves, and reads a few variables, --faq-ink, --faq-gutter (the column of the signs, and where the answers start), --faq-pad (the space above and below a question), --faq-mark and --faq-stroke (the plus): set them on the list, or on anything above it, in a rule of your own. The space under an open answer is the bottom padding of the answer's class.

3. Add custom JS

   To keep things simple, the code ships inside the Webflow embed. You can also copy it here and add it yourself to the page or site custom code. How to choose

4. Use it on your own elements

   Custom attributes
   Select the element on the canvas and open the Settings panel. Under Custom attributes, add a pair: the name on the left, the value on the right.

   Custom attribute	What it does
   data-faq	Marks the list of questions. It takes no value: leave the value field empty. The settings below go on the same element.
   data-faq-item	On the block that holds one question and its answer. It takes no value. Repeat it for each question, three or thirty. Its id is what the address carries: page#delivery opens that question. In Webflow the id is the ID field of the Settings panel. Without an id the engine writes one from the words of the question. [ Required ]
   data-faq-question	On the question: a heading that holds the words and nothing else. It takes no value. The engine puts a real button in it, with the sign before the words. An item without one is left alone and the engine says so in the console. [ Required ]
   data-faq-answer	On the block that holds the answer. It takes no value. It holds anything, one line or three paragraphs, links and lists, and its height is never measured. [ Required ]
   data-faq-open	A state, not a mark to write: the engine puts it on an open item, and takes it off. The button carries aria-expanded, an item on its way data-faq-moving, a list with an answer open data-faq-any, a mounted list data-faq-ready. Never written by hand; the stylesheet reads them, and so can a rule of yours. [ Optional ]

   Settings
   Every setting is a custom attribute too, added the same way and on the same element. An attribute always wins over the defaults written in the code.

   Attribute	Default	What it is
   data-faq-mode	single	How many answers may be open at once. Options: single, opening a question closes the one that was open, and the open one can still be closed; multiple, each question opens and closes on its own, the better choice when readers compare answers.
   data-faq-start	1	The question that is open when the page arrives, when the address names none. Options: a number counted from 1, 2 for the second question; 0 for none; the id of an item, delivery; all, with mode at multiple.
   data-faq-hash	on	Whether the open question is in the address of the page. Options: on, a question opened by the visitor writes the id of its item after the # without adding a step to the history, and an address or a link that names an item, or anything inside one, opens it; off, the address is neither read nor written.
   data-faq-schema	off	Whether the engine adds FAQPage structured data to the head of the page, built from the questions and answers. Options: off, nothing is added; on, one JSON-LD script, see "Structured data" for what it is worth today.
   data-faq-duration	1	The time an answer takes to open or to close, in seconds.

Two files, no build step. It runs in the browser only. Load it with a script tag in plain HTML, in a client-side script in Astro, never in the frontmatter. In React, call FaqAccordion.mount(ref.current) in useEffect and destroy() in its cleanup.

1. Tune it, either way

   Per element with an attribute, or once for the whole site by editing DEFAULTS at the top of the file.

   Attribute	Default	What it is	Lower	Higher
   data-faq-mode	single	How many answers may be open at once. Options: single, opening a question closes the one that was open, and the open one can still be closed; multiple, each question opens and closes on its own, the better choice when readers compare answers.
   data-faq-start	1	The question that is open when the page arrives, when the address names none. Options: a number counted from 1, 2 for the second question; 0 for none; the id of an item, delivery; all, with mode at multiple.
   data-faq-hash	on	Whether the open question is in the address of the page. Options: on, a question opened by the visitor writes the id of its item after the # without adding a step to the history, and an address or a link that names an item, or anything inside one, opens it; off, the address is neither read nor written.
   data-faq-schema	off	Whether the engine adds FAQPage structured data to the head of the page, built from the questions and answers. Options: off, nothing is added; on, one JSON-LD script, see "Structured data" for what it is worth today.
   data-faq-duration	1	The time an answer takes to open or to close, in seconds.	Snappier; under 0.6 the lines are hardly seen rising one by one; 0 opens at once	Slower and more shown; over 1.4 the list feels late on the press

2. Drive it from JavaScript

   When a script opens a question, follows which ones are open, or needs the structured data.
   JavaScript Expand Copy

   const element = document.querySelector('[data-faq]');
   element.addEventListener('faq:settled', (e) => {
     console.log(e.detail);
   });
   
   // Follow what is opened: an analytics call, for one.
   element.addEventListener('faq:change', (event) => {
     console.log(event.detail.item.id, event.detail.open, event.detail.by);
   });
   
   const faq = FaqAccordion.mount(element);   // the list auto() mounted, or a new one
   faq.open('delivery');                       // by the id of an item, or by a number counted from 0
   faq.closeAll();
   console.log(faq.schema());                  // the FAQPage JSON-LD, to paste in the head
   
   // When the list leaves the page:
   FaqAccordion.destroy(element);   // removes what the engine added, gives the markup back as it was

   Show all 17 lines

3. Fit it to your page

   Questions and answers

   • One block per question. A block marked data-faq-item holds a heading marked data-faq-question and a block marked data-faq-answer. To add a question, copy a block; to remove one, delete it; to reorder, move it. In Webflow, duplicate an item in the Navigator, or bind one item to a Collection list.
   • Write the question as plain words in a heading, at the level that fits the page (h3 under an h2). Do not write a button or a sign: the engine puts a real <button> inside the heading, with the sign before the words, and takes them out on destroy().
   • An answer holds anything: one line, three paragraphs, links, lists, a picture. Its height is never measured, so an answer may change while it is open.
   • **Give an item an id** in the page's own words (delivery, not faq-2) when you want a short address. Without one the engine writes an id from the words of the question, how-do-we-pay.
   • Several lists on a page each work on their own.

   The keyboard

   Tab goes from question to question, and into an open answer when it holds a link. Enter or Space opens and closes the question. With the focus on a question, Down and Up go to the next and the previous one round the ends, Home and End to the first and the last.

   The address

   With hash at on, the default:

   • a question opened by the visitor writes # and the id of its item in the address, with history.replaceState: the Back button still leaves the page in one step; closing it takes the # off;
   • a page that arrives with a hash naming an item, or anything inside an answer, opens that question and scrolls to it;
   • a link on the same page to such an id does the same.

   A question opened by a script writes nothing.

   The browser's own search

   A closed answer carries hidden="until-found" where the browser knows it (Chrome and Edge since 102, Firefox since 139): Ctrl+F finds a word inside a closed answer, and the browser opens it, which the engine follows. A link to a piece of text (#:~:text=) does the same. Safari has not shipped it at the time of writing (October 2026): there a closed answer is plainly hidden, and its search does not look inside. In every browser a closed answer is out of the tab order and out of the accessibility tree.

   Structured data

   data-faq-schema="on" adds one <script type="application/ld+json"> to the head: a FAQPage with every question of the list and its answer, the answer keeping its paragraphs, lists and links and nothing else. What it is worth, honestly:

   • Google no longer shows FAQ rich results, the unfolding questions under a search result: limited to government and health sites in August 2023, then ended for every site on 7 May 2026. Google says it still reads the markup to understand the page, and that leaving it in place causes no error. It will not change how the result looks.
   • **Other readers still use FAQPage**: Bing, and the assistants that answer from pages. Most of them do not run JavaScript, so a script added by the engine is not seen by them. For those, call FaqAccordion.mount(element).schema() once in the console, and paste the JSON it returns in a <script type="application/ld+json"> of the page's own head, with the setting left off.
   • **One FAQPage per page.** When the page already carries one, or a second list asks for one, the engine adds nothing and says so.

   The colours and the sizes

   Custom properties, set at zero specificity on the list. Give them your own values on the list or on anything above it:

   • --faq-ink: the questions and their signs.
   • --faq-gutter: the width of the column the signs stand in, which is also where the answers start.
   • --faq-pad: the space above and below the words of a question, 12px in the preview. With the line of the question it makes the step from one question to the next.
   • --faq-mark and --faq-stroke: the size of the plus and the thickness of its bars.

   The type of a question is the heading's own class; the type, the width and the padding of an answer are the answer's own class. The space under an open answer is the answer's bottom padding.

   From JavaScript

   • FaqAccordion.mount(element, overrides) returns the instance of a list, mounting it if it was not: { element, settings, items(), opened(), isOpen(which), open(which, options), close(which, options), toggle(which, options), closeAll(options), schema(), destroy() }. which is a number counted from 0, the id of an item, or an element of one; { instant: true } changes with no motion; each returns false when nothing changed. FaqAccordion.auto(root) mounts every marked list inside root, and runs once on its own; FaqAccordion.destroy(element) gives the markup back.
   • Events, all bubbling from the list: faq:ready; faq:change as soon as a question opens or closes, with { index, item, open, by } in detail, by being user, hash, find or api; faq:settled once everything has stopped, with the numbers of the open questions.
   • The state is in the markup: aria-expanded on the button, data-faq-open on an open item, data-faq-moving on an item on its way, data-faq-any on a list with an answer open, data-faq-ready on the list.
   • **Under prefers-reduced-motion: reduce** a question opens at once.
   • Without JavaScript the page is headings and answers, all of them in sight, in order.
   • The words of the demo are the demo's: on a real page every question and every answer is the user's own, or asked for.

4. Avoid the pitfalls

   • The heading holds words, not a button. A question written as a link or a button ends up as a button inside a button. Plain text, with an emphasis if needed.
   • Do not hide the answers yourself, with CSS or with hidden: the engine does it once it is there, so that a page without JavaScript still shows every answer.
   • **Do not use <details>** for the items: it brings its own opening, which cannot be eased the same way in every browser, and its own state.
   • In Webflow, do not use the native Dropdown or Accordion elements: they bring their own script and classes. The paste is plain blocks.
   • The stylesheet draws the states. Without faq-accordion.css a closed answer is hidden with no motion and no sign shows, and the engine says so in the console.
   • A list at the very top of a short page has no scroll to give: when an answer above closes there, the pressed question moves up with it.
   • **An id used twice on a page** breaks the address: the hash opens the first element that carries it.
   • Questions or answers added after the mount need destroy() then mount(). Text changed inside an answer needs nothing, unless schema is on: the JSON is built once, at the mount.
   • A list inside an answer of another list is left alone by the outer one and mounts on its own.
   • In React or any framework that owns the DOM, mount in an effect and call destroy() in its cleanup; the engine moves the words of each question into a button and wraps each answer in two boxes.

One click on Copy the AI prompt copies everything an assistant needs to build this effect: the complete code, the markup, the dependency, every setting and every pitfall.