ARIA Components

Purpose and Scope

The ARIA component family is the React Aria-backed branch of the shadcn/ui component documentation. The family is presented under the title React Aria and includes a broad catalog of UI patterns such as accordion, alert dialog, breadcrumb, button, calendar, dialog, form, select, sidebar, toast, tooltip, typography, and many more. This page explains the common documentation pattern shown by the supplied ARIA pages: each component is an open-code component that can be installed through the shadcn CLI or copied manually, then composed in application code using named building blocks.

Sources: apps/v4/content/docs/components/aria/meta.json, apps/v4/content/docs/components/aria/accordion.mdx, apps/v4/content/docs/components/aria/alert-dialog.mdx

ARIA pages are useful when a team wants the shadcn/ui visual and composition model while delegating interaction semantics to React Aria primitives. The frontmatter on both supplied component pages marks them as component documentation with base set to aria, and each page links to the relevant React Aria documentation and API reference. In practice, that means the shadcn/ui page teaches installation, import shape, visual variants, and composition, while the upstream React Aria API remains the deeper behavioral reference for props and accessibility semantics.

Sources: apps/v4/content/docs/components/aria/accordion.mdx, apps/v4/content/docs/components/aria/alert-dialog.mdx

Relevant Source Files

• apps/v4/content/docs/components/aria/meta.json — Defines the React Aria documentation group and enumerates the ARIA component pages that belong to the family.
• apps/v4/content/docs/components/aria/accordion.mdx — Shows the standard ARIA component page structure for Accordion, including frontmatter, CLI and manual installation, usage, composition, examples, RTL preview, and API reference handoff.
• apps/v4/content/docs/components/aria/alert-dialog.mdx — Shows the same structure for Alert Dialog, including featured frontmatter, modal-oriented usage, composition with header and footer sections, size API notes, destructive actions, media examples, RTL preview, and React Aria API handoff.

Family Index and Documentation Shape

The family index is intentionally more than a navigation list. By grouping dozens of pages under React Aria, the docs communicate that these components share a backing implementation philosophy and a consistent authoring experience. The list includes simple display primitives, layout helpers, input controls, overlays, menus, data display components, messaging pieces, and form-related components. A reader can therefore learn the page pattern once and apply it across the family: install the component, import the exported parts, assemble the documented composition, then consult the upstream React Aria API when the local examples do not cover an advanced behavior.

Sources: apps/v4/content/docs/components/aria/meta.json

Each individual ARIA page starts with metadata that tells the docs system and the reader what kind of page it is. Accordion is described as a vertically stacked set of interactive headings that reveal content. Alert Dialog is described as a modal dialog that interrupts the user with important content and expects a response, and it is marked as featured. Both declare component true and base aria. Those fields are not just labels; they align the visible documentation, the preview style, and the API links around the ARIA implementation family rather than the Radix or base families.

Sources: apps/v4/content/docs/components/aria/accordion.mdx, apps/v4/content/docs/components/aria/alert-dialog.mdx

Installation and Usage Flow

The installation flow is deliberately repeated across the supplied ARIA pages so users do not need a separate mental model for each component. The preferred path is the shadcn CLI command, for example adding accordion or alert-dialog by name. The manual path installs the shared React Aria dependency, copies the generated component source into the application component directory, and then asks the reader to update import paths for their project. This preserves the project-local ownership model: users add code to their own app rather than depending on a closed component package.

Sources: apps/v4/content/docs/components/aria/accordion.mdx, apps/v4/content/docs/components/aria/alert-dialog.mdx

npx shadcn@latest add accordion
npx shadcn@latest add alert-dialog
npm install react-aria-components

After installation, usage examples focus on named exports from the project component path. Accordion imports its root, item, trigger, and content components, then uses default expanded keys and item identifiers to show an initially open section. Alert Dialog imports trigger, title, description, header, footer, cancel, and action pieces, then wraps a button and dialog together so the trigger opens the modal content. This is the central shadcn/ui pattern for ARIA components: the installed file exports small pieces, and application code owns the final composition.

Sources: apps/v4/content/docs/components/aria/accordion.mdx, apps/v4/content/docs/components/aria/alert-dialog.mdx

import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@/components/ui/accordion"
 
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@/components/ui/alert-dialog"

Composition Patterns

Composition sections are the most important reader-facing bridge between installed source and application markup. Accordion is documented as a root containing repeated items, where each item contains a trigger and content. Alert Dialog is documented as a trigger that contains a button and dialog, with the dialog divided into header and footer regions. The header can include media, title, and description, while the footer contains cancel and action controls. These diagrams help readers preserve accessibility and layout intent even when they customize styling or reorder surrounding application content.

Sources: apps/v4/content/docs/components/aria/accordion.mdx, apps/v4/content/docs/components/aria/alert-dialog.mdx

Accordion
├── AccordionItem
│   ├── AccordionTrigger
│   └── AccordionContent
└── AccordionItem
    ├── AccordionTrigger
    └── AccordionContent

AlertDialogTrigger
├── Button
└── AlertDialog
    ├── AlertDialogHeader
    │   ├── AlertDialogMedia
    │   ├── AlertDialogTitle
    │   └── AlertDialogDescription
    └── AlertDialogFooter
        ├── AlertDialogCancel
        └── AlertDialogAction

The examples then extend the basic composition without changing the underlying model. Accordion demonstrates one-at-a-time behavior, multiple expanded sections through the allows multiple expanded option, disabled items, bordered item styling, and wrapping the accordion in a card. Alert Dialog demonstrates a basic confirmation dialog, a smaller size, media content such as an icon or image, a small dialog with media, and a destructive action variant. These examples show that ARIA components are meant to be customized through props, composition, and surrounding shadcn/ui components rather than by abandoning the documented structure.

Sources: apps/v4/content/docs/components/aria/accordion.mdx, apps/v4/content/docs/components/aria/alert-dialog.mdx

RTL, Preview, and API Reference

Both supplied pages include right-to-left examples that point readers to the RTL configuration guide before rendering an RTL preview. That placement is important: RTL support is presented as a project-level configuration concern plus component-level verification, not as a one-off prop that users add everywhere. The previews use the ARIA Nova style name and, in the RTL examples, set the preview direction to right to left. This makes the docs double as visual regression examples for layout direction, trigger placement, and dialog alignment.

Sources: apps/v4/content/docs/components/aria/accordion.mdx, apps/v4/content/docs/components/aria/alert-dialog.mdx

The API reference pattern is intentionally compact. Accordion sends readers to the React Aria DisclosureGroup API for complete behavior details. Alert Dialog includes one local API note for size, explaining that the content component accepts a size prop with default and small values, then sends readers to the React Aria Modal API for the rest of the component props. This split keeps shadcn/ui documentation focused on the component source it gives users, while acknowledging that interaction state, modal behavior, and accessibility primitives come from React Aria.

Sources: apps/v4/content/docs/components/aria/accordion.mdx, apps/v4/content/docs/components/aria/alert-dialog.mdx

System-to-Code Mapping

For a developer editing or extending the docs, the mapping is straightforward. The meta file controls whether a component appears in the React Aria family navigation. The component MDX files provide frontmatter for title, description, base family, component status, and upstream links. The body then follows a predictable sequence: preview, installation tabs, usage imports and JSX, composition diagram, named example sections, RTL coverage when relevant, and a closing API reference. New ARIA pages should follow this sequence so the family remains consistent for readers moving between components.

Sources: apps/v4/content/docs/components/aria/meta.json, apps/v4/content/docs/components/aria/accordion.mdx, apps/v4/content/docs/components/aria/alert-dialog.mdx

Next Steps

When building with this family, start from the specific component page in the React Aria section, install it with the CLI when possible, and only use the manual path when you need direct copy control. Preserve the documented composition first, then adapt variants, borders, cards, media, destructive actions, and size options to your product. If you need deeper prop behavior than the shadcn/ui examples show, follow the linked React Aria API from the component page. For adjacent concepts, read the broader components overview, the RTL guide, and the focused pages for Accordion, Alert Dialog, and other ARIA-backed components.