@19h47/accordion

@19h47/accordion

Sur un petit air d'accordéon Léon

Accessible accordion for the modern web. Panels are resolved through ariaControlsElements (Baseline 2025), with keyboard support aligned to the WAI-ARIA Accordion pattern.

Requirements

• ESM-capable environment
• Browsers with Element.ariaControlsElements support

Installation

pnpm add @19h47/accordion

Also works with npm / yarn / bun.

Usage

import Accordion from '@19h47/accordion';

const element = document.querySelector('.js-accordion');
const accordion = new Accordion(element);

accordion.init();

<div class="js-accordion">
	<div
		class="js-accordion-panel"
		data-accordion-open="true"
		data-accordion-deselect="true"
	>
		<h3>
			<button
				class="js-accordion-header"
				type="button"
				id="lorem-header"
				aria-expanded="true"
				aria-controls="lorem-body"
			>
				Toggle
			</button>
		</h3>

		<div id="lorem-body" role="region" aria-labelledby="lorem-header">
			<div class="js-accordion-inner">
				Panel content
			</div>
		</div>
	</div>
</div>

The header keeps an aria-controls IDREF in markup. At runtime, the library resolves the panel via ariaControlsElements.

Wrap each header control in a heading (<h2>–<h6>, or nested deeper levels as needed). The library does not inject or enforce this — clean document outline is up to you.

Header: <button> vs <a>

Both work as .js-accordion-header. Choose based on intent:

	<button type="button">	<a href="#panel-id">
Role	Toggle control (APG default)	Link + deep link to the panel
Activation	Click, Enter, Space	Click / Enter (native link)
URL hash	Optional, via your own logic	Native (href + browser history)
Best for	In-page accordion only	Shareable / bookmarkable panels

Use <button> when the header only expands or collapses. Use <a href="#…"> when the panel id should also be a real document fragment.

For deep links, point href at the panel root (.js-accordion-panel, always in the layout), not the collapsible region. A fragment on a hidden / zero-height body makes the browser scroll to the wrong place.

Markup checklist

Selector / attribute	Role
.js-accordion	Root container
.js-accordion-panel	One panel (direct child of the root)
heading (h2–h6)	Wraps the header control (consumer markup; not enforced by the library)
.js-accordion-header	Toggle control (<button> or <a>), sole child of the heading
aria-controls	Points to the panel region id
.js-accordion-inner	Measured content used for height animation
role="region" + aria-labelledby	Accessible name for the panel landmark

Options

Constructor

const accordion = new Accordion(element, {
	multiselectable: false, // allow several panels open at once
});

Option	Type	Default	Description
multiselectable	boolean	false	When false, opening a panel closes the others

You can also set data-accordion-multiselectable="true" on the root in demos; pass the parsed value into the constructor as above.

Panel data attributes

Set these on .js-accordion-panel:

<div
	class="js-accordion-panel"
	data-accordion-open="true"
	data-accordion-deselect="true"
>
	…
</div>

Attribute	Description
data-accordion-open	Initial open state ("true" / "false")
data-accordion-deselect	When "true", an open panel can be collapsed again by its header

Events

import Accordion from '@19h47/accordion';

const accordion = new Accordion(document.querySelector('.js-accordion'));
accordion.init();

for (const panel of accordion.panels) {
	panel.el.addEventListener('Panel.open', ({ detail }) => {
		console.log('opened', detail.current);
	});

	panel.el.addEventListener('Panel.close', ({ detail }) => {
		console.log('closed', detail.current);
	});
}

detail.current is the .js-accordion-panel element.

Keyboard support

Key	Behavior
Space / Enter	Expand or collapse the focused header
Tab / Shift+Tab	Move through focusable elements in page order
↓ / →	Next header (wraps)
↑ / ←	Previous header (wraps)
Home	First header
End	Last header

Accessibility

Role / attribute	Element	Notes
aria-controls	header	IDREF to the panel region; reflected as ariaControlsElements
aria-expanded	header	Updated on open / close
aria-disabled	header	Set to "true" when the panel is open and data-accordion-deselect="false"
role="region"	panel body	Landmark for the expandable content
aria-labelledby	panel body	References the header id

Development

pnpm install
pnpm dev      # Vite playground
pnpm build    # library build → dist/

Demo

Live example: 19h47.github.io/19h47-accordion · source

Acknowledgments

• WAI-ARIA Authoring Practices — Accordion
• Element.ariaControlsElements — MDN
• Accessible toggle tabs and accordion