Accordion

A WAI-ARIA friendly accordion component.

Note: The accordion has been refactored and is not compatible with accordion prior to version 0.9.13

Introduction

An accordion component is a collection of expandable panels associated with a common outer container. Panels consist of a tab header and an associated content region or panel. The primary use of an Accordion is to present multiple sections of content on a single page without scrolling, where all of the sections are peers in the application or object hierarchy. The general look is similar to a tree where each root tree node is an expandable accordion header. The user navigates and makes the contents of each panel visible (or not) by interacting with the Accordion tab header.

Features:

The accordion component relates to the guidelines given in WAI-ARIA Authoring Practices 1.1, Accordion
User interactions via keyboard or mouse
Toggle a particular tab using enter or space key, or by clicking a tab
Client can interact with accordion using a public api og by dispatching a custom action event
The accordion emits a custom toggle events reflecting the tab toggled

To include a MDLEXT accordion component:

1. Code a <ul> element with class="mdlext-accordion mdlext-js-accordion mdlext-accordion--horizontal" to hold the accordion with horizontal layout.

<ul class="mdlext-accordion mdlext-js-accordion mdlext-accordion--horizontal">
</ul>

2. Code a <li> element with class="mdlext-accordion__panel" to hold an individual accordion panel.

<ul class="mdlext-accordion mdlext-js-accordion mdlext-accordion--horizontal">
  <li class="mdlext-accordion__panel">
  </li>
</ul>

3. Code a <header> element with class="mdlext-accordion__tab" to hold the accordion tab header.

<ul class="mdlext-accordion mdlext-js-accordion mdlext-accordion--horizontal">
  <li class="mdlext-accordion__panel">
    <header class="mdlext-accordion__tab">
    </header>
  </li>
</ul>

4. Code a <span> element with class="mdlext-accordion__tab__caption" to hold the accordion tab header caption.

<ul class="mdlext-accordion mdlext-js-accordion mdlext-accordion--horizontal">
  <li class="mdlext-accordion__panel">
    <header class="mdlext-accordion__tab">
      <span class="mdlext-accordion__tab__caption">A tab caption</span>
    </header>
  </li>
</ul>

5. Code a <section> element with class="mdlext-accordion__tabpanel" to hold the tab content.

<ul class="mdlext-accordion mdlext-js-accordion mdlext-accordion--horizontal">
  <li class="mdlext-accordion__panel">
    <header class="mdlext-accordion__tab">
      <span class="mdlext-accordion__tab__caption">A tab caption</span>
    </header>
    <section class="mdlext-accordion__tabpanel">
      <p>Content goes here ...</p>
    </section>
  </li>
</ul>

6. Repeat steps 2..5 for each accordion panel required.

Example

Multiselectable vertical accordion with three panels, aria attributes, ripple effect on each tab header, decorated with a glyph left and a state icon right. Tab #1 is open at page load (aria-expanded="true"). Subscribes to accordion toggle event.

<ul id="my-accordion" 
  class="mdlext-accordion mdlext-js-accordion mdlext-accordion--vertical mdlext-js-ripple-effect"
  role="tablist" aria-multiselectable="true">

  <li class="mdlext-accordion__panel" role="presentation">
    <header class="mdlext-accordion__tab" role="tab" aria-expanded="true">
      <i class="material-icons">dns</i>
      <span class="mdlext-accordion__tab__caption">First section. A long caption should not push the state icon</span>
      <i class="mdlext-aria-toggle-material-icons"></i>
    </header>
    <section class="mdlext-accordion__tabpanel" role="tabpanel" aria-hidden="false">
      <h5>Content #1 goes here</h5>
      <p>Some content <a href="#">with an anchor</a> as a focusable element.</p>
    </section>
  </li>
  <li class="mdlext-accordion__panel" role="presentation">
    <header class="mdlext-accordion__tab" role="tab" aria-expanded="false">
      <i class="material-icons">all_inclusive</i>
      <span class="mdlext-accordion__tab__caption">Tab #2</span>
      <i class="mdlext-aria-toggle-material-icons"></i>
    </header>
    <section class="mdlext-accordion__tabpanel" role="tabpanel" aria-hidden="true" hidden>
      <h5>Content #2 goes here</h5>
      <p>Some content....</p>
    </section>
  </li>
  <li class="mdlext-accordion__panel" role="presentation">
    <header class="mdlext-accordion__tab" role="tab" aria-expanded="false">
      <i class="material-icons">build</i>
      <span class="mdlext-accordion__tab__caption">Tab #3</span>
      <i class="mdlext-aria-toggle-material-icons"></i>
    </header>
    <section class="mdlext-accordion__tabpanel" role="tabpanel" aria-hidden="true" hidden>
      <h5>Content #3 goes here</h5>
    </section>
  </li>
</ul>

<script>
  'use strict';
  window.addEventListener('load', function() {
    var accordion = document.querySelector('#my-accordion');
    accordion.addEventListener('toggle', function(e) {
      console.log('Accordion toggled. State:', e.detail.state, 'Source:', e.detail.tab);
    });
  });
</script>

Note: All required aria attributes will be added by the accordion component during initialization - so it is not strictly necessary to apply the attributes in markup.

More examples

The snippets/accordion.html and the tests provides more detailed examples.
Try out the live demo

Keyboard interaction

The accordion interacts with the following keyboard keys.

Tab - When focus is on an accordion (tab)header, pressing the Tab key moves focus in the following manner:
1. If interactive glyphs or menus are present in the accordion header, focus moves to each in order.
2. When the corresponding tab panel is expanded (its aria-expanded state is 'true'), then focus moves to the first focusable element in the panel.
3. If the panel is collapsed (its aria-expanded state is 'false'), OR, when the last interactive element of a panel is reached, the next Tab key press moves focus as follows:
  - Moves focus to the next logical accordion header.
  - When focus reaches the last header, focus moves to the first focusable element outside the accordion component.
Left arrow
- When focus is on the accordion header, a press of up/left arrow keys moves focus to the previous logical accordion header.
- When focus reaches the first header, further up/left arrow key presses optionally wrap to the first header.
Right arrow
- When focus is on the accordion header, a press of down/right arrow key moves focus to the next logical accordion header.
- When focus reaches the last header, further down/right arrow key presses optionally wrap to the first header
Up arrow - behaves the same as left arrow
Down arrow - behaves the same as right arrow
End - When focus is on the accordion header, an End key press moves focus to the last accordion header.
Home - When focus is on the accordion header, a Home key press moves focus to the first accordion header.
Enter or Space - When focus is on an accordion header, pressing Enter ir Space toggles the expansion of the corresponding panel.
- If collapsed, the panel is expanded, and its aria-expanded state is set to 'true'.
- If expanded, the panel is collapsed and its aria-expanded state is set to 'false'.
Shift+Tab - Generally the reverse of Tab.

Events

Interaction with the component programmatically is performed receiving events from the component or by sending events to the component (or by using the public api).

Events the component listenes to

A client can send a command custom event to the accordion. The command event holds a detail object defining the action to perform and a target for the action.

The detail object has the following structure:

detail: { 
  action, // "open", "close", "toggle" or "upgrade" 
  target  // Target, panel or tab, of action, "undefined" if all panels should be targeted.
          // Note: If you send a null target, the action is cancelled
}

Possible actions are:

open

Open a targeted tab and it's corresponding tabpanel.

myAccrdion = document.querySelector('#my-accordion');
target = myAccordion.querySelector('#my-accordion .mdlext-accordion__panel:nth-child(3)'); 
ce = new CustomEvent('command', { detail: { action : 'open', target: target } });

If target is undefined, the action will open all panels. Note: Opening all panels only makes sense if the accordion has the aria attribute aria-multiselectable set to true, and will be cancelled otherwise.

close

Close a targeted tab and its corresponding tabpanel.

myAccrdion = document.querySelector('#my-accordion');
target = myAccordion.querySelector('#my-accordion .mdlext-accordion__panel:nth-child(3)'); 
ce = new CustomEvent('command', { detail: { action : 'close', target: target } });

If target is undefined, the action will close all panels. Note: Closing all panels only makes sense if the accordion has the aria attribute aria-multiselectable set to true, and will be cancelled otherwise.

toggle

Toggle a targeted tab. Open or close a targeted tab and it's corresponding tabpanel.

myAccrdion = document.querySelector('#my-accordion');
target = myAccordion.querySelector('#my-accordion .mdlext-accordion__panel:nth-child(3)'); 
ce = new CustomEvent('command', { detail: { action : 'toggle', target: target } });

If target is undefined, the action will be cancelled.

upgrade

Upgrade a targeted panel. If you add a panel to the accordion after the page has loaded, you must call upgrade to notify the accordion component about the new panel.

myAccrdion = document.querySelector('#my-accordion');
addedPanel = myAccordion.querySelector('#my-accordion .mdlext-accordion__panel:nth-child(4)'); 
ce = new CustomEvent('command', { detail: { action : 'upgrade', target: addedPanel } });

If target is undefined, the action will be cancelled.

Example: Expand all panels.

var ce = new CustomEvent( 'command', { 
  detail: { 
    action: 'open' 
  } 
});
document.querySelector('#my-accordion').dispatchEvent(ce);

Example: Toggle a spesific tab.

var panel3 = document.querySelector('#my-accordion .mdlext-accordion__panel:nth-child(3) .mdlext-accordion__tab');
var ce = new CustomEvent('command', { 
  detail: { 
    action: 'toggle', 
    target: panel3 
  } 
});
document.querySelector('#my-accordion').dispatchEvent(ce);

Example: Append a new panel.

var panel =
  '<li class="mdlext-accordion__panel">'
  +  '<header class="mdlext-accordion__tab" aria-expanded="true">'
  +    '<span class="mdlext-accordion__tab__caption">New Tab</span>'
  +    '<i class="mdlext-aria-toggle-material-icons"></i>'
  +  '</header>'
  +  '<section class="mdlext-accordion__tabpanel">'
  +    '<h5>New tab content</h5>'
  +    '<p>Some content</p>'
  +  '</section>'
  +'</li>';

var accordion = document.querySelector('#my-accordion');
accordion.insertAdjacentHTML('beforeend', panel);

var theNewPanel = document.querySelector('#my-accordion .mdlext-accordion__panel:last-child');
var ce = new CustomEvent('command', { detail: { action : 'upgrade', target: theNewPanel } });
document.querySelector('#my-accordion').dispatchEvent(ce);

Refer to snippets/accordion.html or the tests for detailed usage.

Events emitted from the component

The accordion emits a custom toggle event when a panel opens or closes. The event has a detail object with the following structure:

detail: {
  state,    // "open" or "close"
  tab,      // the haeder tab element instance that caused the event
  tabpanel  // the cooresponding tabpanel element instance
}

Set up an event listener to receive the toggle event.

document.querySelector('#my-accordion').addEventListener('toggle', function(e) {
  console.log('Accordion toggled. State:', e.detail.state, 'Source:', e.detail.source);
});

Refer to snippets/accordion.html or the tests for detailed usage.

Public methods

upgradeTab(tabOrPanelElement)

Upgrade a targeted panel with aria attributes and ripple effects. If you add a panel to the accordion after the page has loaded, you must call upgrade to notify the accordion component about the newly added panel.

var accordion = document.querySelector('#my-accordion');
var panel3 = document.querySelector('#my-accordion .mdlext-accordion__panel:nth-child(3)');
accordion.MaterialExtAccordion.upgradeTab( panel3 );

command(detail)

Executes an action, targeting a specific tab. The actions corresponds to the custom events defined for this component.

The detail object parameter has the following structure:

detail: { 
  action, // "open", "close", "toggle" or "upgrade" 
  target  // Target, panel or tab, of action, "undefined" if all panels should be targeted.
          // Note: If you send a null target, the action is cancelled
}

open: command( {action: 'open', target: tabOrPanelElement } )

Open a targeted tab and it's corresponding tabpanel.

close: command( {action: 'close', target: tabOrPanelElement } )

Close a targeted tab and it's corresponding tabpanel.

toggle: command( {action: 'toggle', target: tabOrPanelElement } )

Toggle a targeted tab. Open or close a targeted tab and it's corresponding tabpanel.

upgrade: command( {action: 'upgrade', target: tabOrPanelElement } )

Example: Expand all panels.

var accordion = document.querySelector('#my-accordion');
accordion.MaterialExtAccordion.command( {action: 'open'} );

Example: Toggle panel.

var accordion = document.querySelector('#my-accordion');
var panel3 = document.querySelector('#my-accordion .mdlext-accordion__panel:nth-child(3) .mdlext-accordion__tab');
accordion.MaterialExtAccordion.command( {action: 'toggle', target: panel3} );

Refer to snippets/accordion.html or the tests for detailed usage.

Configuration options

The MDLEXT CSS classes apply various predefined visual and behavioral enhancements to the accordion. The table below lists the available classes and their effects.

MDLEXT class	Effect	Remarks
`mdlext-accordion`	Defines container as an MDL component	Required on "outer" `<div>` or `<ul>` element
`mdlext-js-accordion`	Assigns basic MDL behavior to accordion	Required on "outer" `<div>` or `<ul>` element
`mdlext-accordion--horizontal`	Horizontal layot of an accordion	Required. The accordion must have one of `mdlext-accordion--horizontal` or `mdlext-accordion--vertical` defined
`mdlext-accordion--vertical`	Vertical layot of an accordion	Required. The accordion must have one of `mdlext-accordion--horizontal` or `mdlext-accordion--vertical` defined
`mdlext-js-ripple-effect`	Applies ripple click effect to accordion tab header	Optional. Goes on "outer" `<ul>` or `<div>` element
`mdlext-js-animation-effect`	Applies animation effect to accordion tab panel	Optional. Goes on "outer" `<ul>` or `<div>` element
`mdlext-accordion__panel`	Defines a container for each section of the accordion - the tab and tabpanel element	Required on first inner `<div>` element or `<li>` element
`mdlext-accordion__tab`	Defines a tab header for a corresponding tabpanel	Required on `<header>` or `<div>` element
`mdlext-accordion__tabpanel`	The content	Required on `<section>` or `<div>` element

The table below lists available attributes and their effects.

Attribute	Description	Remarks
`aria-multiselectable`	If true, multiple panels may be open simultaneously	Required. Add `aria-multiselectable="true"` to the `mdlext-accordion` element to keep multiple panels open at the same time. If not present, the component will set `aria-multiselectable="false"` during initialization.
`role=tablist`	Component role	Required. Added by component during initialization if not present.
`role=presentation`	Accordion panel role	Required. Added by component during initialization if not present.
`role=tab`	Accordion tab header role	Required. Added by component during initialization if not present.
`aria-expanded`	Accordion tab header attribute. An accordion should manage the expanded/collapsed state of each tab by maintain its aria-expanded state.	Required. Defaults to `aria-expanded="false"`. Set `aria-expanded="true"` if you want a tab to open during page load.
`aria-selected`	Accordion tab header attribute. An accordion should manage the selected state of each tab by maintaining its aria-selected state	Optional. Added by component.
`disabled`	Accordion tab header attribute. Indicates a disabled tab and tabpanel	Optional. If this attribute is present, the tabpanel will not open or close.
`role=tabpanel`	Accordion tabpanel role.	Required. Added by component during initialization if not present.
`aria-hidden`	Accordion tabpanel attribute. An accordion should convey the visibility of each tabpanel by maintaining its aria-hidden state	Required. Added by component.
`hidden`	Accordion tabpanel attribute.	Required. Added by component if `aria-hidden="true"`.

Other examples

The Accordion component is based on / inspired by this CodePen
Open Ajax, Tab Panel: Accordian1
www3 Accordion Example