Skip to content

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

Specification of Accordion.

Accordion includes the following items:

  1. Arrow
    An arrow icon is placed next to the accordion’s label to visually indicate that the accordion can be expanded or collapsed.
  2. Label
    The title or label provides a brief description of the accordion's content. Clicking on this section expands or collapses the accordion.
  3. Description (optional)
    A subtle text could optimally appear to provide more information about the title or label.
  4. 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.
  5. 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.

Different font styles of labeling for accordions.

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.

Different types of expanded content within an accordion.

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.

Scrolling accordion with three accordion items.

Refer to the Accordion component in Codex Figma.

Interaction states

Accordions are divided into collapsed and expanded states as follows:

Interaction states of Accordion for both collapsed and expanded: default, hover, active and focus.

  1. Default collapsed
  2. Hover collapsed
  3. Active collapsed
  4. Focus collapsed
  5. Default expanded
  6. Hover expanded
  7. Active expanded
  8. Focus expanded

Best practices

Consider the following recommendations when using accordions.

Usage

Two accordions with an InfoChip adjacent to their labels.

Do:
  • Use InfoChip next to the label to provide additional information.

Two accordions: one with a warning icon and the other with an InfoChip.

Don't:
  • Mix different elements within the accordions of the same group.

Label

Accordion group with customized label styles.

Do:
  • Customize the label style if needed in your project.
  • Ensure that the label is emphasized more prominently than the expanded content.

Accordion group with customized label colors.

Don't:
  • 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

Accordion group using the icons ‘expand’ and ‘collapse’.

Do:
  • Use the ‘expand’ icon when the accordion is collapsed and the ‘collapse’ one when it's expanded.

Accordion group using the icons ‘add’ and ‘substract’.

Don't:
  • Replace the predefined collapse and expand icons with other icons.

Expanded content

Accordion group with one accordion expanded, containing an image and a set of paragraphs.

Do:
  • 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.

Accordion group with one accordion expanded, containing other nested accordions.

Don't:
  • 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

KeyFunction
TabIt moves the focus to the next interactive element within the Accordion or to the next Accordion in a group.
Shift + TabIt moves the focus to the previous interactive element within the Accordion or to the previous Accordion in a group.
Enter / SpaceIt expands and collapses the accordion content.

Demos

Configurable

Customizable accordion component title

The default slot is the content of the accordion
NameValue
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.

NameValue
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.

NameValue
View
Reading direction

Stacked

It's possible to stack accordions by adding them next to each other in the markup.

Accordion title 1

Accordion content 1

Accordion title 2

Accordion content 2

Accordion title 3

Accordion content 3
NameValue
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 content

Accordion title which is very long and will be properly wrapped to the next line

Accordion content

NameValue
View
Reading direction

With always visible action

To show the icon even when the accordion is collapsed, set the actionAlwaysVisible prop.

Accordion title

Accordion content

Accordion title

Accordion content

Accordion title

Accordion content

NameValue
View
Reading direction

With different content

The accordion can be used with different elements, including images or tables.

Accordion with an image

mediawiki logo

Accordion with a table

 RexBellaMaxLola
BreedGerman ShepherdGolden RetrieverBulldogNova Scotia
Age5372
OwnerJohnSarahMichaelEmily
Eating HabitsHealthy appetitePicky eaterEnjoys treatsLoves homemade meals

Accordion with a textarea

NameValue
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 content 1

Accordion heading h4

Accordion content 2
Accordion heading h5
Accordion content 3
NameValue
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 nameDescriptionTypeValuesDefault
actionAlwaysVisibleForces the accordion to show the action icon.boolean'true', 'false'false
actionIconThe icon that will be displayed on the right side of the accordion header when expanded.Icon-null
actionButtonLabelLabel for the action button. If an action icon is being used, then a label for that icon should be provided for ARIA support.string-''
headingLevelThe heading level of the accordion title.HeadingLevel'h1', 'h2', 'h3', 'h4', 'h5', 'h6''h3'

Events

Event namePropertiesDescription
action-button-clickWhen the action button is clicked.

Slots

NameDescriptionBindings
titleCustomizable Accordion title
descriptionCustomizable Accordion description
defaultCustomizable 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...