Accordion
Shows and hides related sections of secondary content.
On this page
This docs is LLM-friendly and available as clean Markdown.
Supported browser agents can also use WebMCP to search, read, and open these docs. Learn more
Usage
import {
GlAccordion,
GlAccordionItem,
} from "gitlab-ui-react/accordion";<GlAccordion headerLevel={3}>
<GlAccordionItem title="More options">Additional settings</GlAccordionItem>
</GlAccordion>Default
Accordion items expand independently by default, so users can compare content from several sections. Use concise item titles that describe the content they reveal.
Example accordion
An accordion shows and hides related supporting content.
Use one to shorten a page while keeping secondary information nearby.
Yes. Items expand independently unless autoCollapse is enabled.
import {
GlAccordion,
GlAccordionItem,
} from "gitlab-ui-react/accordion";
export default function AccordionExample() {
return (
<GlAccordion headerLevel={3}>
<GlAccordionItem title="What is an accordion?" value="definition">
An accordion shows and hides related supporting content.
</GlAccordionItem>
<GlAccordionItem defaultVisible title="When should I use one?" value="usage">
Use one to shorten a page while keeping secondary information nearby.
</GlAccordionItem>
<GlAccordionItem title="Can several items stay open?" value="behavior">
Yes. Items expand independently unless autoCollapse is enabled.
</GlAccordionItem>
</GlAccordion>
);
}
Single expanded item
Set autoCollapse when opening an item should close its open sibling. Use this behavior when the sections are alternatives and users do not need to compare them.
Accordion with automatic collapse
Define the problem and the desired outcome.
Implement the smallest complete solution.
Test the behavior and review the result.
import {
GlAccordion,
GlAccordionItem,
} from "gitlab-ui-react/accordion";
export default function AccordionAutoCollapseExample() {
return (
<GlAccordion autoCollapse headerLevel={3}>
<GlAccordionItem defaultVisible title="Plan" value="plan">
Define the problem and the desired outcome.
</GlAccordionItem>
<GlAccordionItem title="Build" value="build">
Implement the smallest complete solution.
</GlAccordionItem>
<GlAccordionItem title="Verify" value="verify">
Test the behavior and review the result.
</GlAccordionItem>
</GlAccordion>
);
}
Expanded title
Use titleVisible when the expanded state needs a different action label. The trigger’s accessible name changes with the visible text, so both labels must remain concise and describe the same section.
Different title while expanded
This deployment was created from the main branch and targets production.
import {
GlAccordion,
GlAccordionItem,
} from "gitlab-ui-react/accordion";
export default function AccordionVisibleTitleExample() {
return (
<GlAccordion headerLevel={3}>
<GlAccordionItem
defaultVisible
title="Show deployment details"
titleVisible="Hide deployment details"
value="deployment-details">
This deployment was created from the main branch and targets production.
</GlAccordionItem>
</GlAccordion>
);
}
Accessibility
- Choose
headerLevelto preserve the page’s logical heading hierarchy. An item can override the level only when its position requires it. - Keep every title unique, concise, and descriptive of its panel. Do not rely on the chevron alone to communicate purpose.
- The component supplies native button behavior,
aria-expanded, and the trigger-to-panel relationship. Do not override these attributes. - Keyboard focus remains on the trigger after it expands or collapses. Keep the visible focus indicator intact.
- Do not hide critical information or a page’s primary action in an accordion, and do not nest accordions to create a hierarchy.
API
These are the component-specific props. Both components forward supported div attributes and refs to their outer elements.
GlAccordion
| Prop | Description | Default |
|---|---|---|
headerLevel |
Required heading level, from 1 through 6, inherited by child items. |
— |
autoCollapse |
Closes another open item when an item is expanded. | false |
children |
Accordion items to render. | — |
GlAccordionItem
| Prop | Description | Default |
|---|---|---|
title |
Required text displayed by the collapsed trigger. | — |
titleVisible |
Replaces title while the item is expanded. |
null |
defaultVisible |
Sets the initial expansion state of an uncontrolled item. | false |
visible |
Controls whether the item is expanded. | — |
onVisibleChange |
Runs with the requested expansion state after user interaction or automatic sibling collapse. | — |
value |
Stable identifier used to coordinate sibling items; one is generated when omitted. | — |
headerLevel |
Overrides the inherited heading level for this item. Outside an accordion, the fallback is 3. |
inherited |
headerClass |
Adds clsx-compatible classes to the item’s heading. | — |
children |
Content displayed in the expandable panel. | — |