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.

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

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.

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.

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

Default collapsed
Hover collapsed
Focus collapsed
Default expanded
Hover expanded
Focus expanded

Demos

Configurable

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

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

With description

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.

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.

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.

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.

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

Vue usage

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

Accordion ​

Guidelines ​

Using accordions ​

Specifications ​

Label style ​

Expanded content ​

Scroll ​

Interaction states ​

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

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 Edit

Accordion title Edit

Accordion title Edit

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 ​

Accordion

Guidelines

Using accordions

Specifications

Label style

Expanded content

Scroll

Interaction states

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