FAQ block

Overview

The FAQ block is two pieces: a wrapper <Faq> that owns the title and the surface (or no surface, in flush mode), and any number of <FaqItem> children that each render a question / answer pair. The component deliberately accepts arbitrary JSX for the answer — links, lists, formulas, illustrations — instead of forcing a string.

Variants

Surface is the default — a contained block that reads as its own unit. Flush drops the background and padding so the FAQ becomes part of the surrounding content flow.

Single vs. multi

Single-open keeps the page concise — only one answer is on screen at a time. Multi-open is the right default for browsing FAQs where users compare answers side-by-side. Pick based on whether the user is reading or scanning.

Rich answers

Answers are children, not strings. Drop in lists, links, formulas, or any other markup the answer needs. Just keep them short — the FAQ row should reveal one paragraph or one short list, not an essay. Long answers belong on a dedicated page.

Anatomy

Three parts. The block surface holds the heading and the list; each row holds the question and the icon; opening the row reveals the answer panel directly beneath.

Behavior

• 01Click toggles. Tapping or pressing Enter / Space on a question expands its panel; another press collapses it. There is no separate “close” affordance.
• 02Single-open is opt-in. Default behaviour is multi-open. Pass single to make opening one item collapse the others — accordion semantics without the loaded word.
• 03The plus rotates, it doesn't swap. The icon is two SVG lines: the horizontal stays, the vertical rotates 90° to overlap it. A pure CSS transform means no flicker and no second icon swapping in.
• 04Height animates without measuring. We animate grid-template-rows from 0fr to 1fr with overflow: hidden on the inner cell. The browser interpolates the implicit height for us — no measurement, no layout flicker on first paint.
• 05Reduced motion gets static toggles. Under prefers-reduced-motion, the height transition and the plus rotation skip — the panel snaps open or closed and the icon swap is instant.

Accessibility

The FAQ block uses the disclosure pattern. Each question is a <button> with aria-expanded and aria-controls; the panel is a role="region" with aria-labelledby pointing at the button. The wrapper, when given a string title, becomes a labelled <section> so screen readers can navigate to it as a landmark.

• TabMove focus between questions in source order.
• Enter / SpaceToggle the focused question. Double-press collapses again.
• aria-expandedTrue/false on each button — screen readers announce “expanded” or “collapsed” directly.
• aria-hiddenThe panel is hidden from the a11y tree when collapsed so closed answers aren't announced.

Code

Two patterns: the typical multi-open FAQ on a marketing page, and a single-open variant deep-linked via URL hash.

Multi-open

import { Faq, FaqItem } from "@flatpay-dk/ui";

function CapitalFaq() {
  return (
    <Faq title="Frequently asked questions">
      <FaqItem question="How do I pay my cash advance?">
        A fixed percentage of your daily card sales is automatically deducted
        until your cash advance is fully repaid…
      </FaqItem>
      <FaqItem question="Can I request a different cash advance amount?">
        Offers are calibrated to your typical card-sales volume…
      </FaqItem>
      <FaqItem question="What happens if I don't make any sales?">
        That day's repayment is zero — repayment scales with revenue…
      </FaqItem>
    </Faq>
  );
}

Single-open with deep link

"use client";
import * as React from "react";
import { Faq, FaqItem } from "@flatpay-dk/ui";

function HelpCentreFaq() {
  // Read the URL hash so /help#refunds opens the matching item.
  const [openId, setOpenId] = React.useState<string | null>(null);

  React.useEffect(() => {
    const fromHash = window.location.hash.slice(1);
    if (fromHash) setOpenId(fromHash);
  }, []);

  return (
    <Faq
      title="Help centre"
      single
      openId={openId}
      onOpenChange={(next) => {
        setOpenId(next);
        // Update the URL without reloading so the answer is shareable.
        if (next) history.replaceState(null, "", `#${next}`);
        else history.replaceState(null, "", window.location.pathname);
      }}
    >
      <FaqItem id="refunds" question="How do I issue a refund?">…</FaqItem>
      <FaqItem id="payouts" question="When do payouts arrive?">…</FaqItem>
      <FaqItem id="hardware" question="My terminal won't connect.">…</FaqItem>
    </Faq>
  );
}

Best practices

Props

Faq

FaqItem

Related