FAQ

FAQ section patterns for landing pages and marketing sites. Accordion, grid, and categorized layouts for displaying frequently asked questions.

Overview

FAQ sections help users find answers quickly without contacting support. These patterns use the <accordion-wc> component and native <details> elements, providing accessible expand/collapse behavior with zero custom JavaScript.

Key features:

  • Built on <accordion-wc> for keyboard navigation, ARIA, and indicator styles
  • No custom CSS required for accordion behavior
  • Responsive grid layout for scan-friendly variant
  • Categorized layout for large FAQ lists
  • Progressive enhancement — works without JavaScript

Accordion

The standard FAQ accordion wraps <details> elements in <accordion-wc>. The component handles the chevron indicator, marker hiding, keyboard navigation, and ARIA attributes — no custom CSS needed.

 <accordion-wc data-single> <details name="faq" open> <summary>What is Vanilla Breeze?</summary> <div> <p>A lightweight CSS framework built on modern web standards...</p> </div> </details> <details name="faq"> <summary>How do I get started?</summary> <div> <p>Include via CDN or install via npm...</p> </div> </details> <!-- More items... --> </accordion-wc>

Two-Column Grid

A grid layout that displays all FAQ items at once, arranged in two columns on wider screens. Best for shorter lists (4–8 items) where users benefit from scanning all questions at a glance.

 <div data-layout="grid" data-layout-min="400px" data-layout-gap="xl"> <article class="faq-item" data-layout="stack" data-layout-gap="xs"> <h3>What is Vanilla Breeze?</h3> <p>A lightweight CSS framework...</p> </article> <article class="faq-item" data-layout="stack" data-layout-gap="xs"> <h3>How do I get started?</h3> <p>Include via CDN or install via npm...</p> </article> <!-- More items... --> </div>

Styling

A border-top on each item creates visual separation in the grid:

 .faq-item { border-top: var(--border-width-thin) solid var(--color-border); padding-top: var(--size-m); } .faq-item h3 { font-size: var(--font-size-m); margin: 0 0 var(--size-xs) 0; } .faq-item p { color: var(--color-text-muted); margin: 0; }

Categorized

For large FAQ lists, group questions by topic. Each category gets a heading with an icon, followed by its own <accordion-wc>. This scales well to dozens of questions without overwhelming users.

 <div data-layout="stack" data-layout-gap="2xl"> <div class="faq-category"> <h2><icon-wc name="rocket" size="sm"></icon-wc> Getting Started</h2> <accordion-wc> <details> <summary>What is Vanilla Breeze?</summary> <div><p>Answer...</p></div> </details> <details> <summary>How do I get started?</summary> <div><p>Answer...</p></div> </details> </accordion-wc> </div> <div class="faq-category"> <h2><icon-wc name="settings" size="sm"></icon-wc> Technical</h2> <accordion-wc> <details> <summary>What browsers are supported?</summary> <div><p>Answer...</p></div> </details> <!-- More items... --> </accordion-wc> </div> </div>

Styling

Minimal CSS for the category heading and icon color:

 .faq-category h2 { font-size: var(--font-size-l); margin: 0; display: flex; align-items: center; gap: var(--size-xs); } .faq-category h2 icon-wc { color: var(--color-interactive); }

Usage Notes

  • Accordion vs Grid: Use accordion for longer FAQ lists (6+ items) to save vertical space. Use the grid for shorter lists where scanning all questions at once is helpful.
  • Single-open mode: Add data-single to <accordion-wc> so only one answer is visible at a time. Good for long lists where context switching between answers is unlikely.
  • Bordered variant: Add data-bordered for a contained look with dividers between items. Works well when the FAQ sits alongside other card-based content.
  • Indicator styles: Use data-indicator="plus-minus" for a +/− style instead of the default chevron. See accordion-wc for all options.
  • Open by default: Add the open attribute to a <details> element to have it expanded on page load.
  • Question length: Keep questions concise (under 80 characters). Move complex details to the answer section.
  • Answer formatting: Use paragraphs, lists, and links within answers. Avoid deeply nested content.
  • Grouping: For large FAQ lists (12+ items), the categorized pattern with section headings helps users navigate by topic.
  • SEO: Consider adding FAQPage schema markup if your site is eligible for rich results.

Related

accordion-wc

Accordion component with variants, keyboard nav, and ARIA

Layout Grid

Responsive grid layout element

icon-wc

Icon component for category headings

Feature Patterns

Feature section patterns