A collapsible is a row that opens and closes to show more content, used for FAQ lists and filters. The header can carry a descriptive text, icons, a toggle switch and a number badge. The content animates open.
Every example on this page is the real component, not a picture. Figma: Base / Collapsible, Collapsible & Collapsible open, Support + Visa mer, boxed setup and, for the Storyblok context, Collapsible context examples.
One row. Click the header to open and close it. Choose the size, the theme, the state and the parts of the header and the row and its code update.
The animation is set in Motion.
A collapsible is a row that opens and closes to show more content. The header names the section and can carry a descriptive text, helper text, icons, a toggle switch and a number badge. Rows stack into a list, such as an FAQ or a filter, and share one line between them.
Collapsible has two sizes (Large and Small), a boxed variant (both sizes), a light and a dark theme, and the states enabled, hover and disabled. The content is free: text, a list of checkboxes, supporting text with an action. Each row opens on its own.
In Storyblok this component is the Collapsible block. Its Open switch is the open state of a row (collapsible-wrap--open). The Storyblok widget has its own Storyblok tab in Supernova.
This documentation has three pages. Examples & Guidelines (this page) shows when and how to use a collapsible. Specifications holds the values: tokens, sizes, measurements, states and requirements. Code shows how to add one to a page.
Use a collapsible when the user skims a list and opens one part at a time. Use it for:
When the user must see all the content at once, to compare or to understand the context, hiding part of it limits the understanding. Show the content side by side instead.
Frequent opening and closing frustrates and overwhelms. Open the row that helps the user most from the start (collapsible-wrap--open; the Open switch in Storyblok), for example the first question in a grouped FAQ.
A closed row can be missed. Keep information that people need to continue in plain text.
Write the title as the question or the topic, so the user can scan the closed list. Put the current choice in the descriptive text, not a sentence in the title.
A collapsible inside a collapsible hides the content behind two clicks and harms usability. Use one level, or split the content into separate sections.
A collapsible shows more of one thing. To switch between two views of the same content, use Pill segment control. To move between pages, use Tabs or navigation.
| The user… | Use |
|---|---|
| skims a list of questions or sections and opens one at a time | Collapsible |
| must see all the text | Plain text with headings |
| switches between views of the same content | eco-pill-segment-control |
| moves between pages | Tabs or navigation |
button for the header, with aria-expanded.auto.expand_more icon that rotates 180° when the row is open.max-height; an open row has 32px of space below it.Rows stack into a list and share one line between them. Each row opens on its own.
Title only, with a descriptive text, with a leading icon, with helper text and with a number badge. Combine the parts as the row needs.
A row can hold a setting that turns on and off, such as “Sale items”. Leave out the chevron: a switch inside a header that also opens is a control inside a control.
Large (72px) is the default. Small (56px) has smaller type and 20px icons, for dense layouts such as filters.
A frame around the row, in both sizes. When it is open, a line separates the header from the content, which sits on white. The header is grey only when Header background is on (see Background below).
The line under the row is on by default, so rows in a list share it. The line above is off. Switch each on or off on its own: collapsible-wrap--divider-top adds the top line, collapsible-wrap--no-divider-bottom removes the bottom line. A boxed row has its frame instead.
A row can have a background, surface-raised-secondary, on the header only. It is an add-on in the header part. The content stays on white. Use it to set one row apart in a list, or to give a boxed row a grey header, closed or open. Without it no row is grey, open or closed. The header gets 16px of side padding so the text keeps off the edge, and the content gets the same so it lines up. The content text starts 24px (Large) or 16px (Small) below the grey header.
On a black surface use the dark theme. The line, the text and the number badge change; the layout does not. A filled row in the dark theme has a surface-90 header, and the body and the content stay on the black surface. On hover the title and the descriptive text dim; the helper text stays white.
A disabled row cannot be opened. Text, icons and the badge turn to the disabled colors.
The content is free. These are the compositions in Figma.
Each option has a number of results. A supporting text and a “Show more” action can follow the list.
A filter panel is a list of Large rows. The first row has a top divider. A row can show the current choice as descriptive text, hold a toggle switch with no chevron, or carry a trailing icon and a number of selected values. An open row can start with a search field, followed by the checkbox list.
Supporting text with a “Show more” action and, when the section has a main action, a Secondary button (XSmall).
An intro text and a list of items on grey surfaces, each with a bold title and extra information. The header uses the grey Header background, as in Figma.
A collapsible has two sizes. Large is 72px high and Small is 56px high. Boxed exists in both sizes. The values are under Sizes in Specifications.
The icon and the text sit on the left, the switch, the badge and the chevron on the right with 16px between them. The content lines up with the left edge of the row.
A list sits inside a section. When the list is the last block in its section, the last row’s line is hidden, so no line hangs right above the section’s own padding. When something follows the list, such as a call to action, the line stays. A boxed row always keeps its frame.
A collapsible is as wide as its container. Long titles wrap onto a second line and the header grows.
A collapsible can sit on a white or on a grey section (section--secondary). The grey Header background has the same color as the grey section, so do not combine them.
Use dividers only where they add clarity. In a list the line under each row separates the rows. Switch the lines on and off one by one (see Variants) and follow these rules. A list in a panel or drawer, such as a filter list, starts with a top divider on the first row.
Put lines between the rows only: none above the first row and none under the last. The last row in a section loses its bottom line by itself.
A section with only one collapsible has no neighbours to share a line with, so it gets both the top and the bottom line (--divider-top and --divider-bottom). Not on a colored section: the surface already separates it.
When the section has an optional headline above the collapsible, skip the top divider: the headline already opens the group. On a colored section the row then has no dividers at all.
The title and the icons are black and turn grey on hover. The content is black. Helper text is dark grey and turns lighter on hover; counts and notes are grey. Token names and values are under Design Tokens in Specifications.
A click on the header opens or closes the row. The content grows from zero to its full height and the chevron turns 180°. An open row gets 32px of extra space below the content. A click on the toggle switch changes the switch and does not open the row.
The title, the descriptive text, the icons and the chevron turn to the action hover color. The whole header reacts, not only the text.
The rows are independent. Opening one does not close another.
A disabled row does not react to hover or click and cannot be reached with Tab.
All requirements are listed under Accessibility Requirements in Specifications.
A button header is reached with Tab and opens with Enter or Space. Closed content cannot be reached: it is hidden until the row is open.
The header announces its state through aria-expanded and points to its content with aria-controls. A header with a toggle switch is not a button: the switch is announced on its own, and the row does not open.
aria-expanded and keyboard behavior.