Accordion Container Element

An accessible Custom Element wrapper that adds accordion functionality with keyboard support to a group of headings and panels.

Overview

• ✅ Follows progressive enhancement best practices. E.g. if customElements aren't supported, content falls back to headings and text/panel content.
• ✅ Follows the ARIA Authoring Practices recommendations for accordions.
• 🙌 Inspired by GitHub's tab-container-element.
• ✨See a demo on CodePen✨

Using the Accordion Container Element

The accordion container is published to npm. To install it in your project, run:

npm install accordion-container-element

If you want to use it inside a JS module, you can import the accordion container. The accordion container element defines itself using customElements.define(), so you will not need to use any kind of named import.

import 'accordion-container-element';

You can use it in a regular script tag with the module attribute.

<script type="module" src="path-to/accordion-container/index.js"></script>

<!-- or from a CDN like Unpkg: -->
<script type="module" scr="https://unpkg.com/accordion-container-element@latest/index.js?module">

Accordion markup

By default, the accordion container element has no styling so that you can apply styles however they wish. There are only a couple of requirements for the way the markup inside must be structured.

1. All "summaries" must be a heading (h1-h6) and have a data-summary attribute.
2. All "panels" can be (almost) any HTML element, but must have a data-accordion-panel attribute.

💪 Progressive enhancement

When the accordion container is connected to the DOM the headings inside will be progressively enhanced by wrapping the heading's textContent with a button used for toggling the visibility of each panel. This means that if there's an error loading the script or JavaScript is not available for some reason, all the accordion content will still be accessible as some regular headings and text. 🙌

<accordion-container>
  <h2 data-summary>Panel one summary</h2>
  <div data-panel>
    <p>Panel one content...</p>
  </div>
  <h2 data-summary>Panel two summary</h2>
  <div data-panel>
    <p>Panel two content...</p>
  </div>
  <h2 data-summary>Panel three summary</h2>
  <div data-panel>
    <p>Panel three content...</p>
  </div>
</accordion-container>

Events

The accordion container emits one CustomEvent called accordion-container-toggled. The custom event has a detail object with the following keys/values:

• event.detail.toggle - The summary toggle button that will be toggled if the event is not canceled.
• event.detail.panel - The corresponding panel that will be toggled if the event is not canceled.

Example:

document.addEventListener('accordion-container-toggled', () => {
  if (event.detail.toggle.textContent == 'Panel two summary') {
    console.log('Second panel!');

    // Do stuff only if the second accordion panel was toggled
  }
});

About bundling polyfils, etc.

This element is written in standard ES2017 and does not come transpiled or polyfilled in any way. Depending on your use case and browser support needs you may wish to use the webcomponentsjs polyfill.

Development

To start a local development server that serves the demo/ folder and watches for changes to index.js run the following command in your terminal while in at the root of the repository.

npm start

Tests

This project uses the very excellent Open Web Components testing recommendations.

To run all test run:

npm run test

Test watch mode

To run test in watch mode, run:

npm run test:watch

This will watch all *.test.js files and automatically run tests every time a file changes.