@degjs/expander

expander

A re-usable plugin to manage functionality and accessibility of expanding elements

Install

expander is an ES6 module. Consequently, you'll need an ES^ transpiler (Babel is a nice one) as part of your Javascript workflow.

If you're already using NPM for your project, you can install expander with the following command:

$ npm install @degjs/expander

Usage

The expander plugin will handle listening and responding to click events on a trigger button. It also handles accessibility associated with this (see accessibility section below). Finally, there is built-in support for animation when expanding or collapsing. It will dispatch custom events that the application can listen and respond to.

Note: the expander plugin exports a variable called events to help standardize event names that the app can listen for.

import expander, { events } from '@degjs/expander';

let expanderInst;

const init = () => {
    expanderInst = expander(containerEl);

    containerEl.addEventListener(events.beforeExpand, onBeforeExpand);
};

const destroy = () => {
    expanderInst.destroy();
};

Options

Property Name	Type	Default	Description
isExpanded	Boolean	false	Describes if the content is expanded on init
toggleSelector	String	"button"	The selector string to find the toggle trigger element
controlsId	String	null	The id of the content element that is controlled by the toggle button
expandingCssClass	String	"is-expanding"	The css class to be added when and element is in the process of expanding
collapsingCssClass	String	"is-collapsing"	The css class to be added when and element is in the process of collapsing
expandedCssClass	String	"is-expanded"	The css class to be added when and element is fully expanded
collapsedCssClass	String	"is-collapsed"	The css class to be added when and element is fully collapsed
animationTargetEl	Element	null	The element to add the animation classes to
animationEvent	String	"animationend"	The animation event name to listen for. When it is fired, the expand or collapse action will commence

Methods

getElement()

The getElement method returns the container element used by expander.

Returns

Type	Description
Element	the element that contains the trigger and content for expander

expand()

A way to manually trigger the expand functionality of expander.

collapse()

A way to manually trigger the collapse functionality of expander.

getOptions()

The getOptions method returns the current expander settings.

Returns

Type	Description
Object	the current settings for expander (defaults and user-set options combined)

setOptions(newOptions)

The setOptions method allows changes to the current expander settings. This method performs a merge of the original settings and the new ones.

Arguments

Type	Description
Object	new settings for the expander plugin

Returns

Nothing

destroy()

This method removes any aria-attributes it created and cleans up any event listeners it created.

Accessibility Features

aria-controls

The aria-controls attribute details a relationships between two elements in the DOM. In this module, the aria-controls attribute is added to the toggle element if an element id is provided in the expander options.

It is recommended that the controlsId is passed as an option if the element shown/hidden by the toggle does not immediately follow the toggle in DOM order.

aria-expanded

The aria-expanded attribute details whether a collapsible region is expanded or collapsed.

The expander module will set the aria-expanded attribute to the appropriate value whenever content is expanded or collapsed.

Browser Support

expander depends on the following browser APIs:

• Custom Event: Documentation | Polyfill
• Element.classList.toggle: Documentation | Polyfill

To support legacy browsers, you'll need to include polyfills for the above APIs.