Skip to content
Nexus Application Design nadesign

Accordion

<Accordion> is a vertical stack of [trigger / content] pairs that the user expands on demand. Use for FAQs, settings sub-groups, optional flows.

import from "@na/ui/components/accordion" ▶ Open in Storybook packages/ui/src/components/accordion.tsx

When to use

  • FAQ-style content where most items stay collapsed.
  • Settings panels with optional or advanced sections.
  • Long forms split into “open one at a time” sections.

Don’t use Accordion for: top-level navigation (use Tabs or a sidebar), every body of text — collapse only what the user would skip on a first read, or content the user genuinely needs to see.

Single-open

Only one item can be open at a time. collapsible allows the active item to also close.

 
<Accordion type="single" collapsible>
  <AccordionItem value="a">
    <AccordionTrigger>What is an agent?</AccordionTrigger>
    <AccordionContent>A configured assistant…</AccordionContent>
  </AccordionItem>
  …
</Accordion>

Multiple-open

This panel renders open.

Multiple items can be open simultaneously.

 
<Accordion type="multiple" defaultValue={['a', 'b']}>
  <AccordionItem value="a">…</AccordionItem>
  <AccordionItem value="b">…</AccordionItem>
</Accordion>

API

Accordion

Prop Type Default Description
type * "single" | "multiple" — "single" allows one open at a time; "multiple" allows any number.
collapsible boolean false Only when type="single" — allows closing the open item.
value string | string[] — Controlled active item(s). Array for type="multiple".
defaultValue string | string[] — Initial open item(s).
onValueChange (value) => void — Fires on open/close.

AccordionItem / AccordionTrigger / AccordionContent

AccordionItem requires value (unique within the Accordion).

Design guidelines

✓ Do

  • Use type="single" by default — fewer expanded items keeps the eye anchored.
  • Lead each trigger with a noun phrase or a question. "Tools available" or "What can I run?", not "Tools".
  • Pre-open the most-likely-relevant item with defaultValue when context warrants.

✗ Don't

  • Use Accordion to hide critical content the user must read. Anything required stays visible.
  • Nest Accordions. The visual hierarchy collapses; consider Tabs at one level instead.
  • Use Accordion as the only navigation primitive on a page. Pair with a heading or sidebar.

Accessibility

  • Composes Radix Accordion — triggers are <button aria-expanded>, content has role="region" linked via aria-labelledby.
  • Keyboard: Tab between triggers, Enter / Space toggles. Arrow keys move between triggers.
  • Collapsible — Single trigger / content pair (no list).
  • Tabs — When the user wants to switch between siblings, not disclose them.
  • CollapsibleSection — Page-section flavor for settings.

▶ Open Accordion stories in Storybook