EXEPERTAI LAB

Research alpha

Time Machine
EXEPERTAI LAB
GALLERY / COLLECTION
← Browse Astryx gallery
Collapsible·component·@astryxdesign/core

Collapsible

A primitive that makes any content collapsible: a trigger button toggles visibility of the content area, managing its own state or deferring to a parent CollapsibleGroup.

Open in Playground @astryxdesign/core/Collapsible

Showcases and examples

6 documented examples

Collapsible

An accordion group with three collapsible sections in single mode: opening one closes the others.

Preview loads on approachPreview loads on approach
Exact source · collapsible-showcase
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {Collapsible, CollapsibleGroup} from '@astryxdesign/core/Collapsible';
import {Text} from '@astryxdesign/core/Text';
import {Card} from '@astryxdesign/core/Card';
import {Stack} from '@astryxdesign/core/Stack';

/**
 * Rows inside one card, coordinated so only one is open at a time.
 *
 * Triggers take body-semibold rather than the trigger's default `large`: three
 * rows sharing a single surface are peers, and at 17px semibold each would
 * read as its own section heading. Keep `large` for the case it is for — one
 * Collapsible per card or per Section, where the trigger really is the
 * heading of that surface (see the Multiple Mode and Controlled examples).
 */
export default function CollapsibleShowcase() {
  return (
    <Card width={420}>
      <CollapsibleGroup type="single" defaultValue="notifications">
        <Stack gap={4}>
          <Collapsible
            trigger={
              <Text type="body" weight="semibold">
                General
              </Text>
            }
            value="general">
            <Text type="body" color="secondary">
              Display name, language, and time zone. Time zone drives every date
              shown in the product, including scheduled reports.
            </Text>
          </Collapsible>

          <Collapsible
            trigger={
              <Text type="body" weight="semibold">
                Notifications
              </Text>
            }
            value="notifications">
            <Stack gap={2}>
              <Text type="body" color="secondary">
                Choose which email and push notifications you receive. Mentions
                and direct messages are always delivered — everything else can
                be turned off or batched into a daily digest.
              </Text>
              <Text type="body" color="secondary">
                Quiet hours pause push notifications overnight in your local
                time zone without affecting email.
              </Text>
            </Stack>
          </Collapsible>

          <Collapsible
            trigger={
              <Text type="body" weight="semibold">
                Privacy
              </Text>
            }
            value="privacy">
            <Text type="body" color="secondary">
              Control who can see your profile and activity, and whether your
              workspace appears in search for people outside your organization.
            </Text>
          </Collapsible>
        </Stack>
      </CollapsibleGroup>
    </Card>
  );
}

Usage

Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in CollapsibleGroup for accordion behavior. For custom collapsible components, use the useCollapsible hook directly (astryx hook useCollapsible).

  • Use hasDividers on CollapsibleGroup for FAQ-style lists: built-in row hairlines with themed border tokens, no hand-rolled borders.
  • Wrap each Collapsible in an Card for visual separation in accordion layouts, or use CollapsibleGroup's hasDividers for flat lists; don't combine both.
  • Use CollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.
  • Use type="multiple" when users need to compare content across sections, like feature lists or pricing tiers.
  • Start sections open (defaultIsOpen) when the content is likely needed on first view; don't make users click to see essential info.
  • Hide critical or required content behind a collapsible; users may not discover it.
  • Nest collapsibles more than two levels deep; it makes content hard to find and navigate.
  • Use a collapsible for a single short paragraph; just show the text directly instead.

Typed props

PropType and behavior
triggerReactNode · required
Content shown in the trigger area (always visible).
Slot: Text
childrenReactNode
Content that collapses and expands.
defaultIsOpenboolean · default true
Default open state (uncontrolled).
isOpenboolean
Controlled open state.
isDisabledboolean · default false
Disable the item so its trigger can't be toggled (dimmed, aria-disabled, and out of the tab order). Doesn't collapse an already-open item.
onOpenChange(isOpen: boolean) => void
Callback invoked when the open state changes.
chevronPosition'start' | 'end' · default 'end'
Logical position of Collapsible's disclosure chevron. end (default) follows the label, pointing down when collapsed and up when expanded. start precedes the label, pointing inward toward content when collapsed (mirrored under RTL) and down when expanded. Inside a CollapsibleGroup this defaults to the group's chevronPosition.
valuestring
Identifier used for group coordination. Required when placed inside an CollapsibleGroup.

Anatomy

Trigger · required

The always-visible button that toggles the content. Shows a label and a chevron indicator.

Chevron · optional

Animated disclosure arrow. It follows the label by default; chevronPosition="start" moves it ahead of the label, points inward when collapsed (mirrored under RTL), and turns down when expanded.

Content · optional

The area that hides or reveals when the trigger is clicked.

Accessibility

Trigger label

Color contrast · 1.4.3 Contrast (Minimum) · 4.5:1

The trigger text must have at least 4.5:1 contrast with the surface behind it. For Pointer down, measure against the pressed overlay the trigger row paints while it is pressed.

States: Rest, Pointer down

Theming

Targets

astryx-collapsible

Visual props: density

astryx-collapsible-trigger

Visual props: density

astryx-collapsible-content

Visual props: density

astryx-collapsible-group

Visual props: density