Skip to content
WunderUI

Accordion

Free

Show one section at a time, or several, and keep long pages scannable.

npx wunderui-cli add accordion

Playground

Invoices are issued on the first day of each month and sent to the billing contact. You can download past invoices as PDF files.

Click a row to open it.

Installation

bash
npx wunderui-cli add accordion

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import {
  Accordion,
  AccordionContent,
  AccordionFeedback,
  AccordionItem,
  AccordionRow,
  AccordionTrigger,
} from "@/components/ui/accordion"
import type {
  AccordionAppearance,
  AccordionDensity,
  AccordionHeadingLevel,
} from "@/components/ui/accordion"

Then use it:

tsx
import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@/components/ui/accordion"

export function Faq() {
  return (
    <Accordion appearance="divided" density="default" defaultValue={["refunds"]}>
      <AccordionItem value="refunds">
        <AccordionTrigger>How long does a refund take?</AccordionTrigger>
        <AccordionContent>Refunds reach your original payment method within 5 to 7 business days after approval.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="password">
        <AccordionTrigger>How do I reset my password?</AccordionTrigger>
        <AccordionContent>Open Settings, choose Security and select Reset password.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="plan">
        <AccordionTrigger>Can I change my billing plan?</AccordionTrigger>
        <AccordionContent>You can change your plan at any time in Billing; changes apply immediately.</AccordionContent>
      </AccordionItem>
    </Accordion>
  )
}

Expected result: You should see three rows; the first one is open.

When to use

Use Accordion for

  • FAQs and help pages, where people read one answer at a time
  • Grouped settings, such as account, billing and notifications
  • Long forms split into sections or steps, such as a checkout

Use something else for

  • Collapsible for a single show-more panel
  • Tabs for peer views of one object that people switch between
  • Dialog for a task that must block the page until it is done

Appearance

Four looks for the same list: plain on a page, divided for text rows, contained as one card, separated for stand-alone sections.

Invoices are issued on the first day of each month and sent to the billing contact. You can download past invoices as PDF files.

Behavior

Open one row at a time, or let several stay open.

Invoices are issued on the first day of each month and sent to the billing contact. You can download past invoices as PDF files.

Density

Rows are 48 px high by default and 36 px high in side panels.

Invoices are issued on the first day of each month and sent to the billing contact. You can download past invoices as PDF files.

Trigger content

A row can carry an icon, a description and trailing content next to its label. Controls sit beside the trigger, never inside it.

Item types

Basic
Icon
Description
Counter
Status
Progress
Error summary
Metadata
Restricted

Beside the trigger

Action
Checkbox
Switch

States and content

Hover, pressed, focus and disabled, with the row closed and open, and what a panel shows while it loads, when it is empty and when it fails.

States

Content state

Three files are attached to this request. Open one to preview it.

Keyboard interactions

The trigger is a native button, so the browser provides focus and activation.

TaborShiftTab
Moves focus to the next or previous trigger, and to any control placed beside it with .
EnterorSpace
Opens or closes the focused row. In single mode, opening a row closes the open one.

Arrow keys, Home and End do not move focus between rows in this version.

Behavior and motion

What the list does with state, content, the DOM and motion.

Disabled rows
A disabled item stays focusable and is announced as disabled, but it cannot be toggled. It is drawn at 40 % opacity.
Closed panels are not in the DOM
Closed panels are not rendered by default, so their text is missing from page search and form values inside are lost. You can keep them mounted or let find-in-page open them.
Values are arrays
Values are always arrays of item values, even in single mode, where the array holds at most one. Allow several open rows to hold more.
Always set the look
Look and density are optional. Without a look you get the legacy spaced cards with a +/- button, and rows are 48 px high, so set both in new code.
Headings
Every trigger sits in an h3 by default. Set a heading level from 2 to 6 on the list or on one trigger so the rows fit your page outline.
Opening and closing
Panels grow and shrink with their content. Opening takes the base duration, and closing is one step faster so a dismissed panel does not linger.
Indicators
The plus, minus and cross indicators crossfade in place instead of swapping.
Reduced motion
With reduced motion on, the panel opens and closes instantly and the indicators only fade. Colour changes stay.

Anatomy

The parts the component is made of. Each one renders a you can target from CSS.

Invoices are issued on the first day of each month.
  • data-slot="accordion"

    Tracks which items are open: one at a time by default, several if you allow it. You pick a look (plain, divided, contained, separated) and a density.

  • data-slot="accordion-item"

    One section of the list. It draws the divider, the card or the hover fill, depending on the look of the list.

  • data-slot="accordion-trigger"

    The header row: a real button inside a heading. It can hold a leading icon, a second line, a slot for extra info and an indicator.

  • The question or section name inside the trigger. It is also the button's accessible name.

  • Optional

    A slot between the label and the indicator, for a counter, a status or a short value.

  • The chevron or plus that shows whether the item is open. Its style and position follow the look of the list unless you set them.

  • data-slot="accordion-content"

    The panel under the trigger. It opens smoothly to the height of its content, and its text lines up with the label.

  • data-slot="accordion-feedback"Optional

    The loading, empty and error content of a panel, with an optional action such as Retry.

  • data-slot="accordion-row"Optional

    Wraps the trigger so a control can sit beside it, not inside it: a checkbox or switch on the left, or an action button such as Edit.

Best practices

  • Do

    Pick one look per list: divided or plain on a page, contained as one card, separated for stand-alone sections.

  • Do

    Use the compact density (36 px rows) in side panels and the default (48 px rows) everywhere else.

  • Do

    Allow several open items when people compare answers. By default, opening one closes the other.

  • Do

    Write the trigger as the question or section name in sentence case, like How do refunds work? It is the button's accessible name.

  • Do

    Put controls beside the trigger with AccordionRow. The trigger stays a single button and the control gets its own Tab stop.

  • Don’t

    Don't put buttons or links inside the trigger. The whole row is already a button, and a button inside a button is invalid HTML.

  • Don’t

    Don't hide what people must read or do in a closed row. Required information and primary actions belong outside the accordion.

API reference

One table per part, in the order of the anatomy. Every part also takes the props of the Base UI part it wraps (such as , and ) and the native attributes of its element.

Tracks which items are open: one at a time by default, several if you allow it. You pick a look (plain, divided, contained, separated) and a density.

PropTypeDefaultDescription
appearance"plain" | "divided" | "contained" | "separated"—Visual look of the list: , , or . Without it the list keeps the legacy look (spaced cards with a +/− button), so always set it.
density"compact" | "default""default"Row height: is 48 px, is 36 px.
multiplebooleanfalseWhether multiple items can be open at the same time.
defaultValuestring[]—The values of the items that start open, for an uncontrolled accordion.
valuestring[]—The values of the open items, for a controlled accordion. In single mode the array holds at most one value.
onValueChange(value: string[]) => void—Called with the new array of open item values whenever a row opens or closes.
headingLevel2 | 3 | 4 | 5 | 63Heading level of every trigger, 2 to 6. Defaults to 3.
disabledbooleanfalseWhether the component should ignore user interaction.
loopFocusboolean—No effectDeprecated following the APG guidance update to remove roving focus. This prop no longer affects keyboard focus behavior.

Arrow keys do not move focus in this version, so there is no focus to loop.

orientation"horizontal" | "vertical""vertical"No effectDeprecated following the APG guidance update to remove roving focus. This prop no longer affects keyboard focus behavior.

The accordion is always vertical in this version.

One section of the list. It draws the divider, the card or the hover fill, depending on the look of the list.

PropTypeDefaultDescription
valueany—A unique value that identifies this accordion item. If no value is provided, a unique ID will be generated automatically. Use when controlling the accordion programmatically, or to set an initial open state.
disabledbooleanfalseWhether the component should ignore user interaction.
onOpenChange(open, eventDetails) => void—Event handler called when the panel is opened or closed.
variant"card" | "divider"—Legacy frame of the item: or . Leave it out when you set on the root; the appearance decides.

The header row: a real button inside a heading. It can hold a leading icon, a second line, a slot for extra info and an indicator.

PropTypeDefaultDescription
descriptionReactNode—Optional second line under the label.
metaReactNode—Trailing content between the label and the open/close indicator.
iconReactNode—Optional leading decorative icon.
iconVariant"plain" | "box""box""box" puts the leading icon in a bordered square, "plain" renders it bare.
indicatorVariant"button" | "plus" | "chevron"—The open/close affordance: bordered +/− button, bare +/×, or a chevron.
indicatorPosition"leading" | "trailing""trailing"Where that affordance sits relative to the label.
headingLevel2 | 3 | 4 | 5 | 6—Heading level of this trigger, 2 to 6. Overrides the level set on .
nativeButtonbooleantrueWhether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ).

The panel under the trigger. It opens smoothly to the height of its content, and its text lines up with the label.

PropTypeDefaultDescription
keepMountedbooleanfalseWhether to keep the element in the DOM while the panel is closed. This prop is ignored when is used.
hiddenUntilFoundbooleanfalseAllows the browser's built-in page search to find and expand the panel contents. Overrides the prop and uses to hide the element without removing it from the DOM.

Wraps the trigger so a control can sit beside it, not inside it: a checkbox or switch on the left, or an action button such as Edit.

PropTypeDefaultDescription
leadingReactNode—Control before the trigger, such as a checkbox or a switch. It stays outside the trigger.
actionReactNode—Control after the trigger, such as an Edit button. It stays outside the trigger.
children requiredReactNode—The of the row.

The loading, empty and error content of a panel, with an optional action such as Retry.

PropTypeDefaultDescription
kind required"loading" | "empty" | "error"—Which state the panel shows: , or .
titleReactNode—Heading of the empty and error states.
descriptionReactNode—Supporting line under the title.
actionReactNode—Action under the text, such as a Retry button.
loadingLabelstring—Text under the skeleton while loading. Defaults to .

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("accordion")
Installnpx wunderui-cli add accordion

The full library index for assistants is at /llms.txt.