Accordion & FAQ

4 min · Pattern

AccordionGroup wraps multiple Accordion items with shared borders, dividers, and smart corner radius. Use it for FAQ sections, settings help, and collapsible docs.

What this pattern covers

Grouped collapsible content appears everywhere:

Pricing page FAQ at the bottom
Product docs with expandable answers
Settings panels with help text per section
Mobile navigation sub-menus (see MobileMegaMenu in core)

Once UI provides AccordionGroup for multi-item groups and standalone Accordion for one-off collapsible blocks. Gold reference: packages/core/src/components/AccordionGroup.tsx and the pricing example's FAQ section.

Item shape

AccordionGroup takes a plain items array — each entry has title and content:

Field	Type	Notes
`title`	ReactNode	Question label or section name
`content`	ReactNode	Answer body — usually Text, sometimes a short Column

const faqItems = [
  {
    title: "Can I change plans later?",
    content: (
      <Text onBackground="neutral-weak">
        Yes — upgrade or downgrade anytime from billing settings.
      </Text>
    ),
  },
  {
    title: "Do you offer refunds?",
    content: (
      <Text onBackground="neutral-weak">
        We offer a 14-day money-back guarantee on annual plans.
      </Text>
    ),
  },
];

Keep answers concise. Use Text variant="body-default-s" with onBackground="neutral-weak" for answer body copy.

Basic FAQ section

Wrap the group in a section Column with a heading:

<Column fillWidth maxWidth="m" gap="32">
  <Heading as="h2" variant="display-strong-xs">
    Frequently asked questions
  </Heading>
  {/* AccordionGroup with items={faqItems} */}
</Column>

Pass items={faqItems} to AccordionGroup. The component handles borders, Line dividers between items, and corner radius on the first/last accordion automatically.

autoCollapse behavior

`autoCollapse`	Behavior
`true` (default)	Opening one item closes the others — best for FAQ
`false`	Each accordion manages its own open state — best for independent settings sections

For marketing FAQ pages, keep the default autoCollapse={true} so the list stays scannable.

Split FAQ layout

On wide screens, split questions into two columns for long FAQ lists:

<Grid columns="2" gap="24" s={{ columns: 1 }}>
  <Column gap="16">
    {/* AccordionGroup with first half of items */}
  </Column>
  <Column gap="16">
    {/* AccordionGroup with second half of items */}
  </Column>
</Grid>

4 min · Pattern

AccordionGroup wraps multiple Accordion items with shared borders, dividers, and smart corner radius. Use it for FAQ sections, settings help, and collapsible docs.

What this pattern covers

Grouped collapsible content appears everywhere:

Pricing page FAQ at the bottom
Product docs with expandable answers
Settings panels with help text per section
Mobile navigation sub-menus (see MobileMegaMenu in core)

Item shape

AccordionGroup takes a plain items array — each entry has title and content:

Field	Type	Notes
`title`	ReactNode	Question label or section name
`content`	ReactNode	Answer body — usually Text, sometimes a short Column

const faqItems = [
  {
    title: "Can I change plans later?",
    content: (
      <Text onBackground="neutral-weak">
        Yes — upgrade or downgrade anytime from billing settings.
      </Text>
    ),
  },
  {
    title: "Do you offer refunds?",
    content: (
      <Text onBackground="neutral-weak">
        We offer a 14-day money-back guarantee on annual plans.
      </Text>
    ),
  },
];

Keep answers concise. Use Text variant="body-default-s" with onBackground="neutral-weak" for answer body copy.

Basic FAQ section

Wrap the group in a section Column with a heading:

<Column fillWidth maxWidth="m" gap="32">
  <Heading as="h2" variant="display-strong-xs">
    Frequently asked questions
  </Heading>
  {/* AccordionGroup with items={faqItems} */}
</Column>

Pass items={faqItems} to AccordionGroup. The component handles borders, Line dividers between items, and corner radius on the first/last accordion automatically.

autoCollapse behavior

`autoCollapse`	Behavior
`true` (default)	Opening one item closes the others — best for FAQ
`false`	Each accordion manages its own open state — best for independent settings sections

For marketing FAQ pages, keep the default autoCollapse={true} so the list stays scannable.

Split FAQ layout

On wide screens, split questions into two columns for long FAQ lists:

<Grid columns="2" gap="24" s={{ columns: 1 }}>
  <Column gap="16">
    {/* AccordionGroup with first half of items */}
  </Column>
  <Column gap="16">
    {/* AccordionGroup with second half of items */}
  </Column>
</Grid>

Size	Use for
`s`	Dense settings sidebars, mobile nav
`m` (default)	Marketing FAQ, docs pages
`l`	Hero-adjacent feature lists with long titles

✅ Once UI way	❌ Common mistake
AccordionGroup for 2+ related items	Separate Accordions with manual borders
`title` + `content` item objects	Nesting arbitrary JSX as children of the group
`autoCollapse` for FAQ pages	All items open simultaneously on marketing pages
Text with `onBackground="neutral-weak"` for answers	Raw `<p>` tags with inline color
Split into two groups for two-column FAQ	One group stretched across two Grid cells

What this pattern covers

Item shape

Basic FAQ section

autoCollapse behavior

Split FAQ layout

What this pattern covers

Item shape

Basic FAQ section

autoCollapse behavior

Split FAQ layout

Size variants

Standalone collapsible block

Write this / not this

Check yourself

Accordion & FAQ

What this pattern covers

Item shape

Basic FAQ section

autoCollapse behavior

Split FAQ layout

What this pattern covers

Item shape

Basic FAQ section

autoCollapse behavior

Split FAQ layout

Size variants

Standalone collapsible block

Write this / not this

Check yourself

Related