Skip to content
On this page
You're viewing the docs for the beta version of Codex, which may contain features that have not been released yet. Codex users should visit the official docs.


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.


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

Example of an accordion layout with two Codex Accordions, one expanded displaying a paragraph text and the other one collapsed.


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.

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. Avoid nesting additional accordions within an accordion item to keep the component simple. If you need to represent different subsections within an accordion item, use sub-headers instead.

Different types of expanded content within an accordion.


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, and focus.

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



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.


Reading direction

With description

Reading direction


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

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.


If you are displaying an action button, make sure to provide a label for this button for accessibility purposes by using the actionButtonLabel prop.

Reading direction

With always visible action

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

Reading direction

With different content

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

Reading direction

With different heading levels

The accordion heading can be changed to any heading level by passing the headingLevel prop.

Reading direction

Vue usage


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'


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


titleCustomizable Accordion title
descriptionCustomizable Accordion description
defaultCustomizable Accordion content