Collapsible

Anatomy

import {Collapsible} from '@staffbase/spark';

<Collapsible.Root>
  <Collapsible.Trigger />
  <Collapsible.Content />
</Collapsible.Root>;

API reference

Root

Trigger

Content

When to use

Use a collapsible when a section of secondary content is useful to some people but not to everyone, and showing it all the time would add noise.

• Optional details, such as extra context or advanced options.
• Short, simple content and links.
• Content that people can reveal and compare in place, without leaving the page.

Hiding content has a cost. Some people will not notice it or will not realise they can open it, so only use a collapsible where it helps more than it hurts.

When not to use

• Content everyone needs. If people must read it to complete their task, show it.
• Content you have not tried without a collapsible. Cutting the content down, adding headings or splitting it across pages often works better.
• A series of questions. Put them on separate pages or steps instead.
• Inside another collapsible. Never nest them, because nested content is hard to find.
• Large amounts of content. Closed content still has to load, so heavy content can slow the page down.

Choosing between components

• Use Collapsible to show or hide one section of content in place.
• Use Tabs to switch quickly between sibling sections, where only one is visible at a time.
• Use Popover for small pieces of floating, contextual information that should not move the layout.
• Don’t place a Collapsible inside Tabs or a Popover, or the other way round.

Behaviour

Opening and closing

• The whole trigger is clickable, not only the caret. It works with a click, Enter and Space.
• The content is closed by default. The caret points toward the content when closed and turns down when open, and it mirrors in right-to-left layouts.
• The content animates its height, and the animation is turned off for people who prefer reduced motion.

Starting open

Start closed unless most people need the content. If nearly everyone needs it, show it without a collapsible.

Use defaultOpen to start open, or open and onOpenChange when your own state controls it.

Finding hidden content

Closed content is removed from the page, so browser find-in-page cannot see it. If people are likely to search for text inside, set hiddenUntilFound on Collapsible.Content so that a match opens the section. Browser support varies, so don’t rely on it.

Set keepMounted only when state inside the content must survive closing. Hidden content still renders, and hidden form fields are still submitted.

Content

Trigger label

• Describe what will appear, such as “Publishing options”, not the action, such as “Click to expand”.
• Use sentence case and keep it short. Long labels are tiring to scan and hard for screen reader users to navigate.
• If you struggle to write a clear label, the content may be split in the wrong place. Group it by what people need to do.

Content area

• Keep it simple. Text, lists and links work best.
• The content sits under the trigger with a line on its start side, so the two read as one block. Don’t add your own start padding to line it up.

Don’t disable

Disabled controls confuse people because they give no reason. If a section has nothing to show, remove it. If removing it would be confusing, leave it enabled and explain inside why it is empty.

Accessibility

• The trigger is a native <button> that reports its state with aria-expanded. While the content is open, aria-controls points to it.
• The caret is decorative and hidden from assistive technology, so the label has to carry the meaning.
• Don’t put interactive elements, such as links or buttons, inside the trigger.
• If the label works as a section heading, put the trigger inside a heading element at the right level for the page, such as <h3>.
• Some people, such as those who use speech recognition or navigate by a list of elements, may not realise a label is a button until they interact with it. A clear label helps.

Adapted from the GOV.UK Design System accordion guidance.