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.