Skip to content

Design system

Documentation

DesignComponents / Accordion

Components / Accordion

Beta

Accordion

Use Accordion to reveal related sections in place while keeping each heading and panel keyboard-accessible.

On this page

Examples

Related sections

A named section opens in place while the remaining sections stay available without leaving the page.

See the current members, activity, and shared settings without leaving the workspace.

Accordion with one section open

Multiple sections open

Use multiple when people need to compare or work through more than one section at a time.

Weekly summaries are on. Product announcements remain off until you opt in.

Two-step verification protects all workspace administrator accounts.

Accordion with multiple sections open

Controlled open state

Feature state can coordinate the open items while Accordion keeps the disclosure semantics.

The feature owns the open state when another control needs to coordinate with it.

Open sections: overview

Controlled Accordion with open sections

Unavailable section

A section can remain visible while unavailable in the current context.

This section is available and can be opened or closed normally.

Accordion with a disabled item

Long content

Long supporting content gets its own bounded scroll region instead of clipping the panel or page.

Keep the visible heading short so people can scan the disclosure list.

Put the explanation in the panel and let it wrap naturally at narrow widths.

Bound unusually long supporting material in its own scroll region.

Keep the next action near the content it changes instead of hiding it behind hover.

Use multiple when people need to compare sections side by side.

Accordion with a bounded long-content region

When to use

Use Accordion for related sections that people may need to open without leaving the current page. Keep the headings short and let the panel carry the supporting explanation. Use multiple when people need to compare sections; use Tabs for peer views where only one panel should be visible at a time.

Usage

accordion-basic.tsx
import {
  Accordion,
  AccordionContent,
  AccordionHeader,
  AccordionItem,
  AccordionTrigger,
} from "@phuctech/ui/components/accordion";

export function Example() {
  return (
    <Accordion defaultValue={["overview"]} className="w-full max-w-xl">
      <AccordionItem value="overview">
        <AccordionHeader>
          <AccordionTrigger>Workspace overview</AccordionTrigger>
        </AccordionHeader>
        <AccordionContent>
          See the current members, activity, and shared settings without leaving the workspace.
        </AccordionContent>
      </AccordionItem>
      <AccordionItem value="access">
        <AccordionHeader>
          <AccordionTrigger>Access and permissions</AccordionTrigger>
        </AccordionHeader>
        <AccordionContent>
          Review who can invite teammates, edit settings, and publish changes.
        </AccordionContent>
      </AccordionItem>
    </Accordion>
  );
}

Give each AccordionItem a stable value. The root can be uncontrolled with defaultValue or controlled with value and onValueChange. Compose the heading, trigger, and content parts in that order.

API

Component API
PropTypeDefaultDescriptionConstraints
AccordionRoot propsmultiple=falseOwns the open item values and shared disabled/search behavior.Use one controlled or uncontrolled value model per instance.
defaultValue / valueValue[][]Initial or controlled list of expanded item values.Values must match the item values; use a stable primitive value for each item.
multiplebooleanfalseAllows more than one panel to remain open.Use it when people need to compare or complete sections in parallel.
onValueChange(value, eventDetails) => void—Called after a trigger opens or closes an item.Use it to coordinate feature state; do not mirror it into redundant local state.
hiddenUntilFound / keepMountedbooleanfalseControls closed-panel searchability and DOM retention.Prefer hiddenUntilFound when browser find-in-page should reveal matching content.
AccordionItemItem props—Groups one header and its corresponding panel.Give it a unique value and use disabled only when the reason is clear nearby.
AccordionHeaderheading propsh3Provides the semantic heading for one item.Keep the visible title inside AccordionTrigger.
AccordionTriggerbutton props—Toggles its item and renders the shared chevron affordance.Use a concise visible label; do not replace it with an icon-only trigger.
AccordionContentpanel props—Animated, overflow-hidden panel with the standard content inset.Put long lists in a bounded inner scroll region instead of clipping the page.

Tokens

Component tokens
TokenRoleEffective valueUsage
--color-bg-surface / --color-border-defaultAccordion framesemantic surface and borderKeeps the disclosure group distinct in light and dark themes.
--color-primary / --color-text-secondaryOpen statebrand and muted text rolesThe open trigger and chevron gain emphasis without color-only meaning.
--focus-ring-*Keyboard focusshared focusThe trigger remains visibly focused while navigating with the keyboard.
--motion-duration-fast / --motion-duration-normalDisclosure motionshared motionChevron rotation and panel height stay brief and consistent.

Accessibility

  • Each trigger is a real button inside a heading, so Enter and Space toggle its panel.
  • Keep focus visible and use a heading label that explains the content before it opens.
  • Use stable item values and let the primitive connect each trigger to its panel.
  • Use hiddenUntilFound when important closed content should be discoverable through browser find-in-page.
  • Respect reduced-motion preferences and never make a required instruction available only after expansion.

Do and don’t

Do

Use short, descriptive headings and keep each panel about one related subject.

Don’t

Hide critical actions, unrelated navigation, or a single short sentence behind an Accordion.

  • Tabs keeps peer views visible as one active panel at a time.
  • Card provides a surface when the grouped content should stay visible.
  • Accessibility documents the shared focus and keyboard review.