FAQ Accordion HTML Generator

Accessible FAQ accordions with semantic HTML

A FAQ accordion is the UI pattern where each question collapses into a single line that the visitor can expand to reveal the answer. The pattern keeps long pages scannable, reduces above-the-fold clutter and lets users jump straight to the question that matters to them. Until recently every implementation required JavaScript to toggle aria-expanded, manage focus and animate the panel. Modern browsers ship a native element that handles most of that for free: <details> paired with <summary> is fully keyboard-accessible (Enter and Space toggle, Tab moves focus, the open state is announced by screen readers) and renders without a single line of script.

A typical block looks like this:

<details class="faq">
  <summary>How do I install the package?</summary>
  <p>Run <code>npm install acme</code> from your project root.</p>
</details>

Styling the disclosure marker

By default browsers render a small triangle next to the summary. To hide it use summary::-webkit-details-marker { display: none } in WebKit and summary { list-style: none } for Firefox, then add your own SVG or pseudo-element. Use the details[open] selector to style the open state — rotate a chevron, change the background or shift the text colour to communicate state.

Animating expand and collapse

Native <details> snaps open without a transition. To animate, the most stable workaround is to wrap the answer in an inner div, query its scrollHeight on toggle and transition max-height. A future spec (interest-target / the ::details-content pseudo-element) will allow CSS-only animation, but support is still partial in 2026.

Structured data for rich results

Pair the markup with JSON-LD using Schema.org FAQPage so search engines understand the Q&A list:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "How do I install?",
    "acceptedAnswer": { "@type": "Answer", "text": "Run npm install acme." }
  }]
}
</script>

Important caveat: in August 2023 Google restricted FAQ rich snippets in SERPs to government and authoritative health domains. The structured data is still useful for other crawlers, voice assistants and internal site search, but you should no longer count on the SERP enhancement for a marketing site.

FAQ

Should I use <details> or a JavaScript accordion? Start with <details>. It is accessible out of the box, smaller, faster and continues to work when JS fails. Reach for a framework component (Headless UI, Radix Accordion, Material UI) only when you need animated transitions, "single open at a time" behaviour or deep theming.

Does the FAQ schema still help SEO? Indirectly. Google rarely shows the rich result for non-authoritative sites today, but the JSON-LD still feeds entity extraction, helps voice search and is consumed by Bing and other engines.

How do I open one panel and close the others automatically? Give every <details> the same name attribute — modern browsers treat them as an exclusive group, matching the classic accordion behaviour.

Can I have a panel open by default? Yes, add the boolean attribute open to the relevant <details>.