Accordion β
An Accordion is an expandable and collapsible section of content, often featured in a vertically stacked list with other Accordions. Accordions are commonly used to organize content into collapsed sections, making the interface easier to navigate.
Customizable accordion component title
Name | Value |
---|---|
Props | |
actionIcon | |
actionAlwaysVisible | |
Slots | |
default | |
description | |
title | |
View | |
Reading direction | |
Note: For icon properties, the relevant icon also needs to be imported from the @wikimedia/codex-icons package. See the usage documentation for more information. |
Overview β
When to use Accordion β
Use the Accordion component when you need to organize blocks of content into sections. Avoid using an Accordion when the user needs to read the content by default. In this case, use another component or group of elements instead.
Expanded Accordion content can be as long as needed, and the type of content can vary contextually. Headings should be used to label each section of content.
About Accordion β
Accordion includes the following elements.
Expand icon β
An arrow icon is placed next to the accordionβs label to visually indicate that the Accordion can be expanded or collapsed.
Label β
The title or label provides a brief description of the Accordion's content. Pressing on this section expands or collapses the Accordion.
Customize the label to other styles by applying any of the existing fonts, text sizes or formats defined in our font design tokens.
Always make sure to emphasize the label more prominently than the expanded content.
Avoid customizing the label color as it may lead to contrast issues with the various states of the Accordion.
Avoid combining different text styles within the labels of the same Accordion group.
Avoid including links in the Accordion label.
Description (optional) β
A description can be included to provide more information about the title or label.
Action (optional) β
An action (such as edit) could appear at the end of the heading section and it will affect the entire Accordion item.
Expanded content β
The expanded content within the Accordion can include paragraph text, links, images, videos, tables, or form items. There are no restrictions on the minimum or maximum amount of content that can be included in the expanded section.
- Use sub-headers to represent different subsections within Accordion content.
- Avoid nesting additional Accordions within an Accordion item to create subsections.
Examples β
Basic usage β
Accordion title
The accordion content can be as longer as needed, and the type of content can vary according to the need of each use case.
Headings should be used to label each section of content
This is a very long title which should be moved to the next line if there is not enough space
A paragraph can be added here with a short or long informative text.
Another paragraph can be added here with a short or long informative text. There is no limit to the length of the paragraphs.
Open by default
This Accordion is open by default
Simply add the "open" boolean attribute to this component to have it initially render in the expanded state. All other behavior is unchanged.
With action button β
By default, action buttons display when the Accordion is open.
Accordion title
Accordion title which is very long and will be properly wrapped to the next line
Developer notes
To add an action button to the Accordion, pass the actionButton
prop. The button is placed in the top right corner of the Accordion, and it emits an event actionButtonClicked
when clicked.
If you are displaying an action button, make sure to provide a label for this button for accessibility purposes by using the actionButtonLabel
prop.
With always visible action β
Developer notes
To show the icon even when the Accordion is collapsed, set the actionAlwaysVisible
prop.
With different content β
The Accordion can be used with different elements, including images, tables, or form items..
Accordion with an image

Accordion with a table
Rex | Bella | Max | |
---|---|---|---|
Breed | German Shepherd | Golden Retriever | Bulldog |
Age | 5 | 3 | 7 |
Owner | John | Sarah | Michael |
Eating habits | Healthy appetite | Picky eater | Enjoys treats |
Accordion with a textarea
Heading levels β
By default, the title of an Accordion is an <h3>
element. You can customize the heading level if level 3 is not appropriate for the context. You can also change the text style of the Accordion title using Codex design tokens.
In the example below, the heading level is set to 2 and the font size is increased.
Accordion with h2 title
Accordion with h2 title
Accordion with h2 title
Developer notes
The Accordion heading can be changed to any heading level by passing the headingLevel
prop.
Technical implementation β
Vue usage β
open
Attribute supported
The Accordion component uses a HTML <details>
element under the hood. Adding an open
boolean attribute to this component will cause it to render in the expanded state initially. All other behavior will be unchanged.
Props β
Prop name | Description | Type | Values | Default |
---|---|---|---|---|
actionAlwaysVisible | Forces the accordion to show the action icon. | boolean | 'true' , 'false' | false |
actionIcon | The icon that will be displayed on the right side of the accordion header when expanded. | Icon | - | null |
actionButtonLabel | Label for the action button. If an action icon is being used, then a label for that icon should be provided for ARIA support. | string | - | '' |
headingLevel | The heading level of the accordion title. | HeadingLevel | 'h1' , 'h2' , 'h3' , 'h4' , 'h5' , 'h6' | 'h3' |
Events β
Event name | Properties | Description |
---|---|---|
action-button-click | When the action button is clicked. |
Slots β
Name | Description | Bindings |
---|---|---|
title | Customizable Accordion title | |
description | Customizable Accordion description | |
default | Customizable Accordion content |
CSS-only version β
Markup Structure β
The CSS-only Accordion component is a <details>
element with some custom styling.
CSS-only Accordion Title CSS-only Accordion Description
Lorem ipsum dolor sic amet...
Stacked β
As with the Vue version, multiple Accordion components can be stacked.
Accordion 1
Lorem ipsum dolor sic amet...
Accordion 2
Lorem ipsum dolor sic amet...
Accordion 3
Lorem ipsum dolor sic amet...
Open by default β
As with the Vue version, the Accordion component can default to the expanded state by using the boolean open
attribute.
Open by default This Accordion component is open by default
Lorem ipsum dolor sic amet...
Keyboard navigation β
Key | Function |
---|---|
Tab | It moves the focus to the next interactive element within the Accordion or to the next Accordion in a group. |
Shift + Tab | It moves the focus to the previous interactive element within the Accordion or to the previous Accordion in a group. |
Enter / Space | It expands and collapses the Accordion content. |