Skip to Content

FAQSection

Answer common questions with accessible accordion layouts, optional categories, and local search.

FAQSection displays question and answer data using the UI Accordion primitive. Each item has a stable ID, question, and answer. Category grouping, searchable text, and an empty state are optional.

Beta API maturity: Beta.

Installation

import { FAQSection, type FAQItem } from "@puzzle-ui/pieces";

Variant previews

Disclosures support keyboard activation and either single or multiple expansion. Search filters the current collection locally; it does not call an external search service.

accordion - A conventional expandable list of questions.

390 × 844

two-column - A longer FAQ set arranged into two columns on wider screens.

390 × 844

grid - A set of questions grouped for quick scanning.

390 × 844

cards - Questions in visually separated groups.

390 × 844

split - Questions beside an introduction or support action.

390 × 844

grouped - Questions organized under category headings.

390 × 844

categorized - Questions with in-page links to their categories.

390 × 844

searchable - A question list filtered by a local search field.

390 × 844

minimal - A simple disclosure list with minimal framing.

390 × 844

bordered - A unified disclosure group with an outer border.

390 × 844

numbered - Questions that should be referenced by order.

390 × 844

featured - A set where selected common questions stand out.

390 × 844

API

PropTypeDescription
variantFAQVariantSelects one of twelve FAQ presentations; defaults to accordion.
itemsreadonly FAQItem[]Questions with stable id, question, and answer.
FAQItem.categorystringCategory label for grouped/categorized variants.
FAQItem.searchTextstringOptional text included in searchable filtering.
FAQItem.featuredbooleanAdds a featured label to selected items in the featured variant.
expandMode"single" | "multiple"Accordion expansion mode; defaults to single.
searchLabel / searchPlaceholderstringVisible search label and placeholder.
emptyStateReactNodeOptional custom empty or no-results content.
Shared section propsSectionRootProps and heading propsSemantic root, theme, native attributes, heading, actions, and children.

Usage

<FAQSection
  variant="searchable"
  title="Frequently asked questions"
  items={[
    {
      id: "delivery",
      question: "When will my order arrive?",
      answer: "Delivery usually takes two business days.",
      searchText: "shipping arrival",
    },
  ]}
/>

An empty collection shows a default status message unless emptyState is provided. In categorized mode, category links target IDs generated for that section instance.

Accessibility

Accordion triggers and panels use UI Accordion semantics and keyboard behavior. Search has a visible label, and empty results are announced with a status region. Keep item IDs unique and questions concise.