> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; Aura UI /cdf/aura/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Collapsible

> A single inline expandable block that shows or hides content when triggered.

<Badge color="blue">v1.0.0</Badge> | [View in Storybook](https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-collapsible--docs)

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-collapsible--basic" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-collapsible--basic&viewMode=story&globals=theme:light" title="Collapsible basic story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

## When to use

* You require a mutually exclusive optional or secondary block of content on a page (e.g. AI reasoning, advanced settings, an explanation, a preview).
* When the content is useful but not essential to the primary task.
* Expanding additional details for a single item, such as an expandable table row or a single product detail card.

## When to use something else

* Multiple stacked expandable sections: use [Accordion](/cdf/aura/primitives/accordion) instead.
* Navigation or filtering: use [Tabs](/cdf/aura/primitives/tabs) or filter controls ([Combobox](/cdf/aura/primitives/combobox), [Select](/cdf/aura/primitives/select), etc.).
* Use a [Tooltip](/cdf/aura/primitives/tooltip) or [Popover](/cdf/aura/primitives/popover) for short, temporary visual explanations that floatingly overlay content without pushing surrounding elements down.
* Content the user almost always needs: show it by default as regular text; don't hide it in a collapsible.

## Dos and don'ts

* **Do** default to collapsed unless the collapsible content is the main purpose of the view.
* **Do** keep the trigger label descriptive — it should communicate what's inside, not just say "See more".
* **Do** reserve space or animate layout reflow smoothly to prevent sudden visual jumps for the user.
* **Don't** nest Collapsibles — if you need layered disclosure, reconsider the information architecture.
* **Don't** use it to hide errors, critical or required information or CTAs inside.

## Behavior

* One trigger expands or collapses a single associated region; animation is optional but state (expanded/collapsed) must be exposed to assistive tech when it conveys meaning.
* Collapsibles directly push down subsequent inline content upon expansion and pull it back up upon collapse without changing parent layout boundaries.

## Often used with

[Separator](/cdf/aura/primitives/separator) when stacking multiple collapsible regions on one page.

## Accessibility

* Trigger attributes: Ensure disclosure triggers are semantic `<button>` elements with `aria-expanded="true|false"` linked to the expandable container id via `aria-controls`.
* Focus retention: Do not automatically shift focus into the revealed content container upon expansion unless it contains immediate form fields requiring user input.

## Visual examples

The examples below are interactive and follow the doc site's theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

### Default open

Use a Collapsible that starts expanded when the hidden content is important on first visit—for example, onboarding tips or the primary settings group—so users see it without an extra click.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-collapsible--default-open" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-collapsible--default-open&viewMode=story&globals=theme:light" title="Collapsible default open story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Controlled

Use a controlled Collapsible when open and closed state must follow application logic—for example, syncing with URL parameters, a parent form, or programmatic expand and collapse.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-collapsible--controlled" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-collapsible--controlled&viewMode=story&globals=theme:light" title="Collapsible controlled story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Multiple

Stack multiple Collapsibles on a page when each section toggles independently—for example, advanced settings blocks or optional detail panels that users may open in any combination.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-collapsible--multiple" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-collapsible--multiple&viewMode=story&globals=theme:light" title="Collapsible multiple story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Disabled

Use a disabled Collapsible when the section is temporarily unavailable, and add helper text that explains why the trigger cannot be activated.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-collapsible--disabled" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-collapsible--disabled&viewMode=story&globals=theme:light" title="Collapsible disabled story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### With rich content

Use a Collapsible with rich content when the expanded region includes formatted text, lists, or embedded controls—not just a short paragraph of plain copy.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-collapsible--with-rich-content" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-collapsible--with-rich-content&viewMode=story&globals=theme:light" title="Collapsible with rich content story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Faq

Use a Collapsible for FAQ-style content where each question is a trigger and the answer stays hidden until the user expands that item.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-collapsible--faq" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-collapsible--faq&viewMode=story&globals=theme:light" title="Collapsible faq story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Edge case empty

Handle an empty Collapsible region gracefully by hiding the trigger or showing a message when there is no content to reveal after expansion.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-collapsible--edge-case-empty" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-collapsible--edge-case-empty&viewMode=story&globals=theme:light" title="Collapsible edge case empty story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Edge case long text

Use the long-text Collapsible pattern when expanded content may run to several paragraphs, ensuring the trigger label stays concise while the body can scroll or wrap naturally.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-collapsible--edge-case-long-text" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-collapsible--edge-case-long-text&viewMode=story&globals=theme:light" title="Collapsible edge case long text story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>