FAQs

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add faqs

Usage#

import {
  Faqs,
  FaqsHeader,
  FaqsTitle,
  FaqsDescription,
  FaqsList,
  FaqsItem,
  FaqsFooter,
} from "@/components/ui/faqs"

export function Example() {
  return (
    <Faqs>
      <FaqsHeader>
        <FaqsTitle>Frequently asked questions</FaqsTitle>
        <FaqsDescription>Everything you need to know.</FaqsDescription>
      </FaqsHeader>
      <FaqsList>
        <FaqsItem question="Is Koala UI free to use?">
          The core library is free under a permissive license.
        </FaqsItem>
      </FaqsList>
    </Faqs>
  )
}

Stacked layout#

The default layout="stacked" centers the header above a width-constrained list. It is the classic centered FAQ, ideal at the foot of a landing page. Set a defaultValue on FaqsList (matching a FaqsItem value) to open the first answer so the section never reads as an empty stack of triggers.

Split layout#

Set layout="split" for a two-column grid: a header column that stays sticky while the list scrolls beside it (the Stripe / Linear FAQ). The columns stack on mobile, and FaqsFooter spans both columns underneath.

Grouped by topic#

For a long, categorized help center, slot FaqsGroups between the header and footer. Each takes a title (an <h3> under the section <h2>) and an optional description, then wraps its own questions, so the page reads header → topic → questions → topic. Each group owns its own list, so single-expand is scoped to the topic and the hairline dividers reset at every boundary. It defaults to the borderless minimal list, and still forwards every FaqsList prop (variant, defaultValue, iconPosition, …).

Landing scale#

size="lg" on Faqs is the landing-page FAQ: topic headings big enough to scan the page by, and every list inside defaults to the Accordion's own lg step (an 18px semibold question on a taller row), so questions and topics step up together. The first topic sits flush, because a landing FAQ usually has its lede in a SectionHeader above the block. Pair it with marker="plus".

List style#

FaqsList forwards straight to the Accordion, so its variant controls the chrome: card (the default: one bordered box with shared dividers), minimal (borderless rows divided by hairlines), or separated (each item its own bordered box). None of those three paints a fill, so the list takes the ground it sits on, whether that is the page or a muted band. The fourth, pill, is the chip list: a closed question hugs its own text and the open one floods into a filled card, for a short FAQ sitting beside a picture rather than filling the measure on its own.

Helpful feedback#

For a help-center / knowledge-base FAQ, set iconPosition="leading" on FaqsList to move the caret ahead of the question, and add feedback to a FaqsItem to mount a Helpful / Not helpful voting row beneath its answer. The chosen pill stays emphasized while the other dims, and an acknowledgement fades in. For full control (custom labels, an onVote handler), drop a FaqsFeedback into the answer yourself.

Footer call to action#

FaqsFooter is an optional closing row for a contact prompt. Drop a line of copy beside one of our Button components; it centers in the stacked layout and spans both columns in the split layout.

Composition#

The parts are plain composition, so a list of questions maps cleanly into FaqsItems. Give each one a stable value when you want to target it with defaultValue; omit it and a unique id is generated for you.

API reference#

Parts: Faqs, FaqsHeader, FaqsTitle, FaqsDescription, FaqsGroup, FaqsList, FaqsItem, FaqsFeedback, FaqsFooter. FaqsList forwards all Accordion props; each part forwards its native props and merges className last.

FAQ#