Robust and accessible

  • As it relies on a basic HTML structure (Hx and contents), even if the JavaScript isn’t loaded, your page will work, it’s the miracle of progressive enhancement;
  • It is based on ARIA Design Pattern for accordions;
  • No inline CSS/JavaScript injected, your DOM stays clean, which is cool for responsive.

It’s (highly) customisable

  • You can style it as you want;
  • You can set up transitions or animations… as you want;
  • You can create namespaces for generated classes if you need different behaviours in the same page;
  • Every aspect of the script can be customized, if you transpile the script into ES5, it will be IE9+ compatible.

Free and no license problem

  • No license problem: it uses MIT license, so it’s free, open-source and you can do whatever you want with it, including commercial use. This permission notice shall be included in all copies or substantial portions of it.
  • However, it is not prohibited to tell me that you’ve used it, or send me a little “thank you”. ;)

Lightweight

  • 19kb (development, readable by humans);
  • ~5kb (minified, readable by machines);
  • ~3kb minified and gzipped (readable by… mutants‽‽)

How it is working

Basically it will transform this:

<div class="js-accordion" data-accordion-prefix-classes="your-prefix-class">
 <h2 class="js-accordion__header">First tab</h2>
 <div class="js-accordion__panel">
   <p>Content of 1st tab</p>
 </div>
 <h2 class="js-accordion__header">Second tab</h2>
 <div class="js-accordion__panel">
   <p>Content of 2nd tab</p>
 </div>
 <h2 class="js-accordion__header">Third tab</h2>
 <div class="js-accordion__panel">
   <p>Content of 3rd tab</p>
 </div>
</div>

Into this:

<div class="your-prefix-class" 
   data-accordion-prefix-classes="your-prefix-class"
   role="tablist" aria-multiselectable="true">

 <button id="accordion1_tab1" 
     class="js-accordion__header your-prefix-class__header" 
     aria-controls="accordion1_panel1" aria-expanded="false" 
     role="tab" aria-selected="true" type="button">
       First tab
 </button>

 <div id="accordion1_panel1" 
     class="js-accordion__panel your-prefix-class__panel" 
     aria-labelledby="accordion1_tab1" 
     role="tabpanel" aria-hidden="true">

   <h2 class="your-prefix-class__title" tabindex="0">First tab</h2>
   <p>Content of 1st tab</p>

 </div>
 … etc…
</div>

The plugin will do the rest (all ids, ARIA attributes, buttons are generated on the fly).

How to use it

You may use npm command: npm i van11y-accessible-accordion-aria.
You may also use bower: bower install van11y-accessible-accordion-aria.

Then, follow the conventions given in this minimal example.

<div class="js-accordion" data-accordion-prefix-classes="your-prefix-class">
 <h2 class="js-accordion__header">First tab</h2>
 <div class="js-accordion__panel">
   <p>Content of 1st tab</p>
 </div>
 <h2 class="js-accordion__header">Second tab</h2>
 <div class="js-accordion__panel">
   <p>Content of 2nd tab</p>
 </div>
 <h2 class="js-accordion__header">Third tab</h2>
 <div class="js-accordion__panel">
   <p>Content of 3rd tab</p>
 </div>
</div>

The minimal style needed is:

.your-prefix-class__panel[aria-hidden=true] {
  display: none;
}

How to style it (nicely)

In this example page, I’ve used data-accordion-prefix-classes="minimalist-accordion", so all the generated classes will start with .minimalist-accordion (.minimalist-accordion__header, .minimalist-accordion__panel and .minimalist-accordion__title).

.minimalist-accordion__panel[aria-hidden=true] {
  display: none;
}

.minimalist-accordion__header {
  display: block;
}

/* title opened */
.minimalist-accordion__header[aria-expanded="true"]:before {
  content: "- ";
}
/* title closed */
.minimalist-accordion__header[aria-expanded="false"]:before {
  content: "+ ";
}

/* title selected */
.minimalist-accordion__header[aria-selected="true"]:after {
  content: " (sel)";
}
/* title non selected */
.minimalist-accordion__header[aria-selected="false"]:after {
  content: " (unselc)";
}

Keyboard shortcuts

Keyboard navigation is supported too, here are the shortcuts:

If you focus on the accordion “buttons”:

  • use Up/Left to put focus on previous accordion button,
  • use Down/Right to put focus on next accordion button
  • use Home to put focus on first accordion button (wherever you are in accordion buttons)
  • use End to put focus on last accordion button (wherever you are in accordion buttons)

And strike space or return on an accordion button to open/close it.

If you focus on accordion content:

  • use Ctrl Up to set focus on the accordion button for the currently displayed accordion content
  • use Ctrl PageUp to set focus on the previous accordion button for the currently displayed accordion content
  • use Ctrl PageDown to set focus on the next accordion button for the currently displayed accordion content

Warning: Ctrl+PageUp/PageDown combination could activate for some browsers a switch of browser tabs. Nothing to do for this, as far as I know (if you have a solution, let me know).

Bonuses

Content opened by default

If you want to have an accordion content opened by default, just add the attribute data-accordion-opened="true" on a hx, example:

<h2 class="js-accordion__header" data-accordion-opened="true">
 Second tab
</h2>

And the script will open its content.

Other options

The ARIA Design Pattern for accordions allows to have several accordion panels opened at the same time (which is shown by the attribute aria-multiselectable="true"). However, you might need to avoid this for design purposes or client request. To do this, you may set this attribute on the accordion container: data-accordion-multiselectable="none". Example:

<div class="js-accordion" data-accordion-multiselectable="none">

This option will set up aria-multiselectable="false" and the script will allow only one panel to be opened at the same time.