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

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.

Specifications

Specification of Accordion.

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.

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.

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

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

Do:

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

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.

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

The default slot is the content of the accordion

Name	Value
Props
actionIcon
actionAlwaysVisible
Slots
default
description
title
View
Reading direction	Left to right (LTR) Right to left (RTL)
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

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

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.

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.

NPMMediaWiki

vue

<template>
	<cdx-accordion>
		<template #title>
			Accordion title
		</template>
		<p>
			The accordion content can be as longer as needed, and the type of content can vary
			according to the need of each use case.
		</p>
		<p>Headings should be used to label each section of content</p>
	</cdx-accordion>
	<cdx-accordion>
		<template #title>
			This is a very long title which should be moved to the next line if there is
			not enough space
		</template>
		<p>A paragraph can be added here with a short or long informative text.</p>
		<p>
			Another paragraph can be added here with a short or long informative text.
			There is no limit to the length of the paragraphs.
		</p>
	</cdx-accordion>
	<cdx-accordion open>
		<template #title>
			Open by default
		</template>
		<p>This Accordion is open by default</p>
		<p>
			Simply add the "open" boolean attribute to this component to have it
			initially render in the expanded state. All other behavior is unchanged.
		</p>
	</cdx-accordion>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxAccordion } from '@wikimedia/codex';

export default defineComponent( {
	name: 'AccordionDefault',
	components: { CdxAccordion }
} );
</script>

vue

<template>
	<cdx-accordion>
		<template #title>
			Accordion title
		</template>
		<p>
			The accordion content can be as longer as needed, and the type of content can vary
			according to the need of each use case.
		</p>
		<p>Headings should be used to label each section of content</p>
	</cdx-accordion>
	<cdx-accordion>
		<template #title>
			This is a very long title which should be moved to the next line if there is
			not enough space
		</template>
		<p>A paragraph can be added here with a short or long informative text.</p>
		<p>
			Another paragraph can be added here with a short or long informative text.
			There is no limit to the length of the paragraphs.
		</p>
	</cdx-accordion>
	<cdx-accordion open>
		<template #title>
			Open by default
		</template>
		<p>This Accordion is open by default</p>
		<p>
			Simply add the "open" boolean attribute to this component to have it
			initially render in the expanded state. All other behavior is unchanged.
		</p>
	</cdx-accordion>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxAccordion } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'AccordionDefault',
	components: { CdxAccordion }
} );
</script>

Name	Value
View
Reading direction	Left to right (LTR) Right to left (RTL)

With description

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

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.

NPMMediaWiki

vue

<template>
	<cdx-accordion>
		<template #title>
			Accordion title
		</template>
		<template #description>
			This is a description for the accordion
		</template>
		<p>
			The accordion content can be as longer as needed, and the type of content can vary
			according to the need of each use case.
		</p>
		<p>Headings should be used to label each section of content</p>
	</cdx-accordion>
	<cdx-accordion>
		<template #title>
			This is a very long title which should be moved to the next line if there is not
			enough space
		</template>
		<template #description>
			The description can be a very long and sometimes it is needed to wrap it to the next
			line
		</template>
		<p>A paragraph can be added here with a short or long informative text.</p>
		<p>
			Another paragraph can be added here with a short or long informative text.
			There is no limit to the length of the paragraphs.
		</p>
	</cdx-accordion>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxAccordion } from '@wikimedia/codex';

export default defineComponent( {
	name: 'AccordionDescription',
	components: { CdxAccordion }
} );
</script>

vue

<template>
	<cdx-accordion>
		<template #title>
			Accordion title
		</template>
		<template #description>
			This is a description for the accordion
		</template>
		<p>
			The accordion content can be as longer as needed, and the type of content can vary
			according to the need of each use case.
		</p>
		<p>Headings should be used to label each section of content</p>
	</cdx-accordion>
	<cdx-accordion>
		<template #title>
			This is a very long title which should be moved to the next line if there is not
			enough space
		</template>
		<template #description>
			The description can be a very long and sometimes it is needed to wrap it to the next
			line
		</template>
		<p>A paragraph can be added here with a short or long informative text.</p>
		<p>
			Another paragraph can be added here with a short or long informative text.
			There is no limit to the length of the paragraphs.
		</p>
	</cdx-accordion>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxAccordion } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'AccordionDescription',
	components: { CdxAccordion }
} );
</script>

Name	Value
View
Reading direction	Left to right (LTR) Right to left (RTL)

Stacked

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

Accordion content 1

Accordion content 2

Accordion content 3

Name	Value
View
Reading direction	Left to right (LTR) Right to left (RTL)

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 content

NPMMediaWiki

vue

<template>
	<cdx-accordion
		:action-icon="cdxIconEdit"
		action-button-label="Edit"
		@action-button-click="handleButtonClick"
	>
		<template #title>
			Accordion title
		</template>
		Accordion content
	</cdx-accordion>
	<cdx-accordion
		:action-icon="cdxIconEdit"
		action-button-label="Edit"
		@action-button-click="handleButtonClick"
	>
		<template #title>
			Accordion title which is very long and will be properly wrapped to the next line
		</template>
		Accordion content
	</cdx-accordion>
	<br>
	<p v-if="showHandleButtonClickResult">
		Action button clicked
	</p>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxAccordion } from '@wikimedia/codex';
import { cdxIconEdit } from '@wikimedia/codex-icons';

export default defineComponent( {
	name: 'AccordionActionButton',
	components: { CdxAccordion },
	setup() {
		const showHandleButtonClickResult = ref( false );
		const handleButtonClick = () => {
			showHandleButtonClickResult.value = true;
			setTimeout( () => {
				showHandleButtonClickResult.value = false;
			}, 2000 );
		};

		return {
			cdxIconEdit,
			handleButtonClick,
			showHandleButtonClickResult
		};
	}
} );
</script>

vue

<template>
	<cdx-accordion
		:action-icon="cdxIconEdit"
		action-button-label="Edit"
		@action-button-click="handleButtonClick"
	>
		<template #title>
			Accordion title
		</template>
		Accordion content
	</cdx-accordion>
	<cdx-accordion
		:action-icon="cdxIconEdit"
		action-button-label="Edit"
		@action-button-click="handleButtonClick"
	>
		<template #title>
			Accordion title which is very long and will be properly wrapped to the next line
		</template>
		Accordion content
	</cdx-accordion>
	<br>
	<p v-if="showHandleButtonClickResult">
		Action button clicked
	</p>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxAccordion } = require( '@wikimedia/codex' );
const { cdxIconEdit } = require( './icons.json' );

// @vue/component
module.exports = defineComponent( {
	name: 'AccordionActionButton',
	components: { CdxAccordion },
	setup() {
		const showHandleButtonClickResult = ref( false );
		const handleButtonClick = () => {
			showHandleButtonClickResult.value = true;
			setTimeout( () => {
				showHandleButtonClickResult.value = false;
			}, 2000 );
		};

		return {
			cdxIconEdit,
			handleButtonClick,
			showHandleButtonClickResult
		};
	}
} );
</script>

Name	Value
View
Reading direction	Left to right (LTR) Right to left (RTL)

With always visible action

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

Accordion content

NPMMediaWiki

vue

<template>
	<cdx-accordion
		:action-icon="cdxIconEdit"
		action-always-visible
		action-button-label="Edit"
		@action-button-click="handleButtonClick"
	>
		<template #title>
			Accordion title
		</template>
		Accordion content
	</cdx-accordion>
	<cdx-accordion
		:action-icon="cdxIconEdit"
		action-always-visible
		action-button-label="Edit"
		@action-button-click="handleButtonClick"
	>
		<template #title>
			Accordion title
		</template>
		Accordion content
	</cdx-accordion>
	<cdx-accordion
		:action-icon="cdxIconEdit"
		action-always-visible
		action-button-label="Edit"
		@action-button-click="handleButtonClick"
	>
		<template #title>
			Accordion title
		</template>
		Accordion content
	</cdx-accordion>
	<br>
	<p v-if="showHandleButtonClickResult">
		Action button clicked
	</p>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxAccordion } from '@wikimedia/codex';
import { cdxIconEdit } from '@wikimedia/codex-icons';

export default defineComponent( {
	name: 'AccordionActionVisible',
	components: { CdxAccordion },
	setup() {
		const showHandleButtonClickResult = ref( false );
		const handleButtonClick = () => {
			showHandleButtonClickResult.value = true;
			setTimeout( () => {
				showHandleButtonClickResult.value = false;
			}, 2000 );
		};

		return {
			cdxIconEdit,
			handleButtonClick,
			showHandleButtonClickResult
		};
	}
} );
</script>

vue

<template>
	<cdx-accordion
		:action-icon="cdxIconEdit"
		action-always-visible
		action-button-label="Edit"
		@action-button-click="handleButtonClick"
	>
		<template #title>
			Accordion title
		</template>
		Accordion content
	</cdx-accordion>
	<cdx-accordion
		:action-icon="cdxIconEdit"
		action-always-visible
		action-button-label="Edit"
		@action-button-click="handleButtonClick"
	>
		<template #title>
			Accordion title
		</template>
		Accordion content
	</cdx-accordion>
	<cdx-accordion
		:action-icon="cdxIconEdit"
		action-always-visible
		action-button-label="Edit"
		@action-button-click="handleButtonClick"
	>
		<template #title>
			Accordion title
		</template>
		Accordion content
	</cdx-accordion>
	<br>
	<p v-if="showHandleButtonClickResult">
		Action button clicked
	</p>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxAccordion } = require( '@wikimedia/codex' );
const { cdxIconEdit } = require( './icons.json' );

// @vue/component
module.exports = defineComponent( {
	name: 'AccordionActionVisible',
	components: { CdxAccordion },
	setup() {
		const showHandleButtonClickResult = ref( false );
		const handleButtonClick = () => {
			showHandleButtonClickResult.value = true;
			setTimeout( () => {
				showHandleButtonClickResult.value = false;
			}, 2000 );
		};

		return {
			cdxIconEdit,
			handleButtonClick,
			showHandleButtonClickResult
		};
	}
} );
</script>

Name	Value
View
Reading direction	Left to right (LTR) Right to left (RTL)

With different content

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

	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

NPMMediaWiki

vue

<template>
	<cdx-accordion>
		<template #title>
			Accordion with an image
		</template>
		<img
			alt="mediawiki logo"
			src="https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/MediaWiki-2020-logo.svg/1920px-MediaWiki-2020-logo.svg.png"
		>
	</cdx-accordion>
	<cdx-accordion>
		<template #title>
			Accordion with a table
		</template>
		<table>
			<tr>
				<th>&nbsp;</th>
				<th>Rex</th>
				<th>Bella</th>
				<th>Max</th>
				<th>Lola</th>
			</tr>
			<tr>
				<th>Breed</th>
				<td>German Shepherd</td>
				<td>Golden Retriever</td>
				<td>Bulldog</td>
				<td>Nova Scotia</td>
			</tr>
			<tr>
				<th>Age</th>
				<td>5</td>
				<td>3</td>
				<td>7</td>
				<td>2</td>
			</tr>
			<tr>
				<th>Owner</th>
				<td>John</td>
				<td>Sarah</td>
				<td>Michael</td>
				<td>Emily</td>
			</tr>
			<tr>
				<th>Eating Habits</th>
				<td>Healthy appetite</td>
				<td>Picky eater</td>
				<td>Enjoys treats</td>
				<td>Loves homemade meals</td>
			</tr>
		</table>
	</cdx-accordion>
	<cdx-accordion>
		<template #title>
			Accordion with a textarea
		</template>
		<cdx-text-area placeholder="Start typing..." />
	</cdx-accordion>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxAccordion, CdxTextArea } from '@wikimedia/codex';

export default defineComponent( {
	name: 'AccordionDifferentContent',
	components: { CdxAccordion, CdxTextArea }
} );
</script>

vue

<template>
	<cdx-accordion>
		<template #title>
			Accordion with an image
		</template>
		<img
			alt="mediawiki logo"
			src="https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/MediaWiki-2020-logo.svg/1920px-MediaWiki-2020-logo.svg.png"
		>
	</cdx-accordion>
	<cdx-accordion>
		<template #title>
			Accordion with a table
		</template>
		<table>
			<tr>
				<th>&nbsp;</th>
				<th>Rex</th>
				<th>Bella</th>
				<th>Max</th>
				<th>Lola</th>
			</tr>
			<tr>
				<th>Breed</th>
				<td>German Shepherd</td>
				<td>Golden Retriever</td>
				<td>Bulldog</td>
				<td>Nova Scotia</td>
			</tr>
			<tr>
				<th>Age</th>
				<td>5</td>
				<td>3</td>
				<td>7</td>
				<td>2</td>
			</tr>
			<tr>
				<th>Owner</th>
				<td>John</td>
				<td>Sarah</td>
				<td>Michael</td>
				<td>Emily</td>
			</tr>
			<tr>
				<th>Eating Habits</th>
				<td>Healthy appetite</td>
				<td>Picky eater</td>
				<td>Enjoys treats</td>
				<td>Loves homemade meals</td>
			</tr>
		</table>
	</cdx-accordion>
	<cdx-accordion>
		<template #title>
			Accordion with a textarea
		</template>
		<cdx-text-area placeholder="Start typing..."></cdx-text-area>
	</cdx-accordion>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxAccordion, CdxTextArea } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'AccordionDifferentContent',
	components: { CdxAccordion, CdxTextArea }
} );
</script>

Name	Value
View
Reading direction	Left to right (LTR) Right to left (RTL)

With different heading levels

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

Accordion content 1

Accordion content 2

Accordion content 3

Name	Value
View
Reading direction	Left to right (LTR) Right to left (RTL)

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.

Lorem ipsum dolor sic amet...

Stacked

As with the Vue version, multiple Accordion components can be stacked.

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.

Lorem ipsum dolor sic amet...

Accordion ​

Guidelines ​

Using accordions ​

Specifications ​

Label style ​

Expanded content ​

Scroll ​

Interaction states ​

Best practices ​

Usage ​

Label ​

Expand icon ​

Expanded content ​

Keyboard navigation ​

Demos ​

Configurable ​

Customizable accordion component title

Default ​

Accordion title

This is a very long title which should be moved to the next line if there is not enough space

Open by default

With description ​

Accordion title This is a description for the accordion

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

Stacked ​

Accordion title 1

Accordion title 2

Accordion title 3

With action button ​

Accordion title

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

With always visible action ​

Accordion title

Accordion title

Accordion title

With different content ​

Accordion with an image

Accordion with a table

Accordion with a textarea

With different heading levels ​

Accordion heading h2

Accordion heading h4

Accordion heading h5

Vue usage ​

Props ​

Events ​

Slots ​

CSS-only version ​

Markup Structure ​

CSS-only Accordion Title CSS-only Accordion Description

Stacked ​

Accordion 1

Accordion 2

Accordion 3

Open by default ​

Open by default This Accordion component is open by default

Accordion

Guidelines

Using accordions

Specifications

Label style

Expanded content

Scroll

Interaction states

Best practices

Usage

Label

Expand icon

Expanded content

Keyboard navigation

Demos

Configurable

Default

With description

Stacked

With action button

With always visible action

With different content

With different heading levels

Vue usage

Props

Events

Slots

CSS-only version

Markup Structure

Stacked

Open by default