Collapsible

A Collapsible is a single expandable section. Use it wherever content should be progressively revealed without a page transition — order summaries, stack traces, DNS settings, build logs, environment variables, and more.

This component is built on top of React Aria's Disclosure primitive, giving you managed focus, correct ARIA attributes, and keyboard interaction for free.

Installation

npx @tailgrids/cli add collapsible

Anatomy

Import the three composable parts and assemble them.

import {
  Collapsible,
  CollapsibleTrigger,
  CollapsibleContent
} from "@/components/collapsible";

export default function CollapsibleAnatomy() {
  return (
    <Collapsible>
      <CollapsibleTrigger />
      <CollapsibleContent />
    </Collapsible>
  );
}

Usage

Import the three composable parts and assemble them.

import {
  Collapsible,
  CollapsibleTrigger,
  CollapsibleContent
} from "@/registry/core/collapsible";

export default function Example() {
  return (
    <Collapsible>
      <CollapsibleTrigger>Can I use this in my project?</CollapsibleTrigger>
      <CollapsibleContent>
        Yes. Free to use for personal and commercial projects. No attribution
        required.
      </CollapsibleContent>
    </Collapsible>
  );
}

Examples

Controlled

The collapsible component can be controlled using isExpanded and onExpandedChange. In this example, we show an error summary with a "Stack trace" section that can be toggled open to reveal more details.

Default Open

By default, the collapsible component is closed. You can open it by default using defaultExpanded prop on Collapsible component.

Disabled

You can use isDisabled to prevent the user from expanding or collapsing the panel.

Order Summery

With Icon

Interactive

You can create a fully interactive collapsible component using the Collapsible component.

API Reference

Collapsible

The root component. Wraps React Aria's Disclosure and accepts all its props.

CollapsibleTrigger

The heading + button element that toggles the panel. Renders a semantic heading wrapping a <button slot="trigger">.

CollapsibleContent

The collapsible panel that shows content when the trigger is activated. Maps to React Aria's DisclosurePanel.

The panel is hidden from the accessibility tree when collapsed. React Aria handles the hidden attribute automatically.

Accessibility

• Semantics — The trigger is a <button> inside a heading element (h3 by default). This creates the correct heading hierarchy for screen readers.
• ARIA attributes — aria-expanded and aria-controls are automatically managed by React Aria. No manual wiring required.
• Keyboard support — Press Space or Enter on the focused trigger to expand or collapse the panel.
• Focus management — Focus styles are visible when navigating by keyboard (focus-visible).
• Disabled state — When isDisabled is set, the trigger receives disabled and is removed from the tab order.
• Heading level — Use the level prop on CollapsibleTrigger to match the heading hierarchy of the surrounding page content.