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.
Guidelines
When to use accordions
Use the Accordion component when you need to organize blocks of content into sections. Avoid using an accordion component 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.
Specifications
Accordion includes the following items:
- Arrow
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. Clicking on this section expands or collapses the accordion. - Description (optional)
A subtle text could optimally appear to provide more information about the title or label. - Action (optional)
An action (such as edit) could optionally appear at the end of the heading section and it will affect the entire accordion item. - Accordion’s content
When the accordion is expanded, its content becomes visible, and the arrow icon rotates to show the expanded state.
Component limitations
The accordion's label and description have no minimum or maximum length restrictions. However, shorter labels are encouraged, as additional information about the label can be included in a description below.
Label style
By default, the label text style is set to the base font in bold. However, it can be easily customized 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.
Expanded content
The content within the accordion can include paragraph text, menu items, 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.
Scroll
If the accordion's content exceeds the viewport height, the entire accordion will be vertically scrolled. There will be no scrolling within the expanded content of the accordion.
Refer to the Accordion component in Codex Figma.
Interaction states
Accordions are divided into collapsed and expanded states as follows:
- Default collapsed
- Hover collapsed
- Active collapsed
- Focus collapsed
- Default expanded
- Hover expanded
- Active expanded
- Focus expanded
Best practices
Consider the following recommendations when using accordions.
Usage
- Use InfoChip next to the label to provide additional information.
- Mix different elements within the accordions of the same group.
Label
- Customize the label style if needed in your project.
- Ensure that the label is emphasized more prominently than the expanded content.
- Customize the label color as it may lead to contrast issues with the various states of the Accordion.
- Combine different text styles within the labels of the same accordion group.
- Include links in the accordion label.
Expand icon
- Use the ‘expand’ icon when the accordion is collapsed and the ‘collapse’ one when it's expanded.
- Replace the predefined collapse and expand icons with other icons.
Expanded content
- Include paragraph text, menu items, links, images, videos, tables, or form items within the accordion content.
- Use sub-headers to represent different subsections within an accordion item.
- Nest additional accordions within an accordion item to create subsections. If you need to represent different subsections within an accordion item, use sub-headers instead.
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. |
Demos
Configurable
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. |
Default
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.
Name | Value |
---|---|
View | |
Reading direction |
With description
Accordion title This is a description for the accordion
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 The description can be a very long and sometimes it is needed to wrap it to the next line
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.
Name | Value |
---|---|
View | |
Reading direction |
Stacked
It's possible to stack accordions by adding them next to each other in the markup.
Accordion title 1
Accordion title 2
Accordion title 3
Name | Value |
---|---|
View | |
Reading direction |
With action button
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.
TIP
If you are displaying an action button, make sure to provide a label for this button for accessibility purposes by using the actionButtonLabel
prop.
Accordion title
Accordion title which is very long and will be properly wrapped to the next line
Name | Value |
---|---|
View | |
Reading direction |
With always visible action
To show the icon even when the accordion is collapsed, set the actionAlwaysVisible
prop.
Name | Value |
---|---|
View | |
Reading direction |
With different content
The accordion can be used with different elements, including images or tables.
Accordion with an image
Accordion with a table
Rex | Bella | Max | Lola | |
---|---|---|---|---|
Breed | German Shepherd | Golden Retriever | Bulldog | Nova Scotia |
Age | 5 | 3 | 7 | 2 |
Owner | John | Sarah | Michael | Emily |
Eating Habits | Healthy appetite | Picky eater | Enjoys treats | Loves homemade meals |
Accordion with a textarea
Name | Value |
---|---|
View | |
Reading direction |
With different heading levels
The accordion heading can be changed to any heading level by passing the headingLevel
prop.
Accordion heading h2
Accordion heading h4
Accordion heading h5
Name | Value |
---|---|
View | |
Reading direction |
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 just 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...