Accordion

Purpose and Scope

Accordion is the shadcn/ui component for a vertically stacked set of interactive headings where each heading reveals a related section of content. In practice, it is the right primitive for FAQs, settings groups, collapsible details, and dense documentation panels where content needs to remain discoverable without occupying the full page at once. The docs treat Accordion as a component with the same public composition across ARIA, Base UI, and Radix-backed variants: an Accordion root contains one or more AccordionItem elements, each item contains an AccordionTrigger, and each trigger controls an AccordionContent region.

The important reader task is choosing and installing the right implementation while keeping application code predictable. The shadcn/ui model does not hide the component inside an opaque package; the CLI copies component code into components/ui/accordion.tsx, and manual setup asks you to install the underlying primitive package, paste the component source, and adjust import paths. That means teams can start from a documented default, then change styling, structure, spacing, icons, or behavior in their local codebase without waiting on a library release.

Sources: apps/v4/content/docs/components/aria/accordion.mdx, apps/v4/content/docs/components/base/accordion.mdx, apps/v4/content/docs/components/radix/accordion.mdx

Relevant Source Files

apps/v4/content/docs/components/aria/accordion.mdx - Defines the React Aria-backed Accordion docs, including installation with react-aria-components, usage with defaultExpandedKeys, composition, visual examples, RTL preview, and the React Aria API reference link.
apps/v4/content/docs/components/base/accordion.mdx - Defines the Base UI-backed Accordion docs, including installation with @base-ui/react, usage with defaultValue, multiple, disabled items, styling examples, RTL preview, and the Base UI API reference link.
apps/v4/content/docs/components/radix/accordion.mdx - Defines the Radix-backed Accordion docs, including installation with radix-ui, usage with type, collapsible, defaultValue, multiple mode, disabled items, styling examples, RTL preview, and the Radix UI API reference link.
apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx - Explains the rewritten CLI model behind npx shadcn add, including component dependency shipping, framework support, Tailwind updates, remote components, schema support, and monorepo improvements.
apps/v4/content/docs/changelog/2025-04-shadcn-2-5.mdx - Documents “resolve anywhere,” the registry installer behavior that tracks files and performs multi-pass import and alias resolution when registry content is installed.
apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx - Explains the create workflow where users pick a component library, visual style, icons, base color, theme, and fonts, with code rewritten to match the selected setup.

Installation and Source Model

All three Accordion docs expose the same primary CLI command: npx shadcn@latest add accordion. This command is the recommended path because the component can bring along the implementation code and dependency information needed by the selected registry style. The August 2024 CLI changelog is relevant because it describes the rewritten CLI as a distribution system for code that can install components, themes, hooks, utilities, and more with npx shadcn add. It also calls out Accordion as an example of a component that can define its own Tailwind keyframes, with the CLI updating project configuration during installation.

Manual installation differs by implementation. The ARIA variant installs react-aria-components, the Base UI variant installs @base-ui/react, and the Radix variant installs radix-ui. After installing the dependency, the docs instruct readers to copy the generated source into components/ui/accordion.tsx and update import paths for the project. This is more than a fallback path: it reflects the repository’s open-code philosophy, where component ownership transfers to the application and where local aliases such as @/components/ui/accordion are expected to match the consuming project’s configuration.

Sources: apps/v4/content/docs/components/aria/accordion.mdx, apps/v4/content/docs/components/base/accordion.mdx, apps/v4/content/docs/components/radix/accordion.mdx, apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx

npx shadcn@latest add accordion

Usage and Composition

The common import surface is intentionally stable across the documented implementations. Application code imports Accordion, AccordionContent, AccordionItem, and AccordionTrigger from @/components/ui/accordion. The tree shape is also stable: the root coordinates item state, each item identifies a collapsible section, the trigger is the interactive heading, and the content is the body revealed by that trigger. This makes it possible to switch implementation families or generated styles without teaching every feature team a different component anatomy.

The state props are where the variants diverge. React Aria examples use defaultExpandedKeys on the root and id on each item, with allowsMultipleExpanded for multi-open behavior and isDisabled for disabled items. Base UI examples use defaultValue with item value, multiple for multi-open behavior, and disabled on the item. Radix examples use type="single" or type="multiple", collapsible, defaultValue, item value, and disabled. The conceptual behavior is the same, but these prop names should follow the selected underlying primitive.

Sources: apps/v4/content/docs/components/aria/accordion.mdx, apps/v4/content/docs/components/base/accordion.mdx, apps/v4/content/docs/components/radix/accordion.mdx

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

<Accordion type="single" collapsible defaultValue="item-1">
  <AccordionItem value="item-1">
    <AccordionTrigger>Is it accessible?</AccordionTrigger>
    <AccordionContent>
      Yes. It adheres to the WAI-ARIA design pattern.
    </AccordionContent>
  </AccordionItem>
</Accordion>

Variants, Styling, and RTL

The docs present the same example family for each implementation: Basic, Multiple, Disabled, Borders, Card, RTL, and API Reference. Basic demonstrates a single item open by default. Multiple demonstrates the prop that allows more than one section to remain open. Disabled demonstrates disabling an individual item rather than the whole group. Borders demonstrates adding border to the root and border-b last:border-b-0 to items, while Card demonstrates wrapping the Accordion in a Card component for a contained panel layout.

RTL support is documented through a dedicated preview with direction="rtl", and each implementation points readers to the RTL configuration guide rather than redefining global direction setup on the component page. That separation matters: Accordion can render correctly in a right-to-left preview, but application-wide RTL behavior depends on shared configuration outside the component itself. When validating an Accordion in an RTL interface, test trigger placement, icon direction, focus movement, and border or radius choices after applying the global RTL setup.

The December 2025 create changelog adds an additional design dimension. It describes npx shadcn create as a workflow for choosing the component library, icons, base color, theme, fonts, and visual style, including styles such as Vega, Nova, Maia, Lyra, and Mira. For Accordion, this means the generated source can reflect not only a color theme but also spacing, structure, typography, and primitive-library choices. The docs examples already show implementation-specific style names such as aria-nova, base-nova, and radix-nova, reinforcing that style and primitive selection are connected.

API Components

Component or prop	ARIA variant	Base UI variant	Radix variant	Purpose
`Accordion`	Root with `defaultExpandedKeys` and `allowsMultipleExpanded`	Root with `defaultValue` and `multiple`	Root with `type`, `collapsible`, and `defaultValue`	Coordinates which items are expanded.
`AccordionItem`	Uses `id`; disables with `isDisabled`	Uses `value`; disables with `disabled`	Uses `value`; disables with `disabled`	Defines one collapsible section.
`AccordionTrigger`	Shared public component	Shared public component	Shared public component	Renders the interactive heading control.
`AccordionContent`	Shared public component	Shared public component	Shared public component	Renders the revealed panel content.
Multiple-open mode	`allowsMultipleExpanded`	`multiple`	`type="multiple"`	Allows more than one item to remain open.
API reference target	React Aria DisclosureGroup API	Base UI Accordion API	Radix Accordion API	Upstream primitive documentation for deeper prop details.

Treat the table as a bridge between shadcn/ui’s stable composition and the selected primitive’s state API. The local component file is yours after installation, but the underlying accessibility and behavior contracts still come from React Aria, Base UI, or Radix UI. When adding custom animation, nested controls, or analytics hooks, preserve the trigger/content relationship and keep item identity values stable. If you migrate from one primitive family to another, update root and item state props first, then check disabled behavior, multiple-open behavior, and any tests that assume exact prop names.

Sources: apps/v4/content/docs/components/aria/accordion.mdx, apps/v4/content/docs/components/base/accordion.mdx, apps/v4/content/docs/components/radix/accordion.mdx

Registry and Upgrade Considerations

Accordion is installed through the same registry-aware system as other shadcn/ui components. The 2024 CLI changelog explains that the installer supports major React frameworks, remote component URLs, registry schemas, better error handling, and monorepo support. The 2025 “resolve anywhere” update further explains that registries can place files anywhere in an app and that installation tracks files with multi-pass import and alias resolution. For Accordion users, those behaviors matter when the component is added to a nonstandard app structure, a monorepo package, or a registry that also contributes utilities, styles, or dependent files.

A practical workflow is to start with the CLI install, confirm the dependency chosen by your implementation family, inspect components/ui/accordion.tsx, and then adapt the component to match your design system. Use Basic to validate default expansion, Multiple to validate state shape, Disabled to validate unavailable content, Borders and Card to validate layout treatments, and RTL to validate internationalized direction. Next, read the broader component-family page for your selected primitive and the CLI or registry pages if you need to publish a customized Accordion through a private registry.

Sources: apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx, apps/v4/content/docs/changelog/2025-04-shadcn-2-5.mdx, apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx

Ask a question...