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.
two-column - A longer FAQ set arranged into two columns on wider screens.
grid - A set of questions grouped for quick scanning.
cards - Questions in visually separated groups.
split - Questions beside an introduction or support action.
grouped - Questions organized under category headings.
categorized - Questions with in-page links to their categories.
searchable - A question list filtered by a local search field.
minimal - A simple disclosure list with minimal framing.
bordered - A unified disclosure group with an outer border.
numbered - Questions that should be referenced by order.
featured - A set where selected common questions stand out.
API
| Prop | Type | Description |
|---|---|---|
variant | FAQVariant | Selects one of twelve FAQ presentations; defaults to accordion. |
items | readonly FAQItem[] | Questions with stable id, question, and answer. |
FAQItem.category | string | Category label for grouped/categorized variants. |
FAQItem.searchText | string | Optional text included in searchable filtering. |
FAQItem.featured | boolean | Adds a featured label to selected items in the featured variant. |
expandMode | "single" | "multiple" | Accordion expansion mode; defaults to single. |
searchLabel / searchPlaceholder | string | Visible search label and placeholder. |
emptyState | ReactNode | Optional custom empty or no-results content. |
| Shared section props | SectionRootProps and heading props | Semantic 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.