Accessible Toggle

Accessible and responsive toggling of an element's visibility. Supports a media-query option, which will enable or disable the toggle based on screen size (e.g. for "hamburger" menus that should only be toggleable on small screens).

Usage

Initialize Accessible Toggle with the content element as the first argument. You may also pass in an optional second argument: an object containing the configuration options (see below).

import accessibleToggle from 'accessible-toggle';

const toggle = new Toggle(document.getElementById('navigation'), {
  mediaQuery: '(max-width: 600px)',
});

The toggle controls should have a data-toggle attribute, set to the value of the content element's ID.

<button data-toggle="navigation">Menu</button>
<nav id="navigation">
  ...
</nav>

Suggested CSS

By itself, this script will only toggle the appropriate ARIA roles, which won't cause any visual change. You need to include the following CSS somewhere in your stylesheet to make the element actually disappear and appear.

[aria-hidden='true'] {
  display: none;
}

Of course you can also implement your own styles to provide transition effects, etc.

Installation

Install via yarn

yarn add accessible-toggle

or npm

npm install accessible-toggle

Configuration

You can pass in extra options as a configuration object. The following options are supported:

trapFocus

When the panel is open, prevent the user from tabbing out of it. (Default: true)

assignFocus

Set this to true if you want to automatically move focus to the first link or button within the content after is is shown. (Default: true)

closeOnEsc

Allow the user to press the escape key to hide the content. (Default: true) Set this to true if you want to automatically move focus to the first link or button within the content after is is shown. (Default: true)

closeOnClickOutside

Close the panel when the user clicks on any other element on the page. (Default: false)

mediaQuery

If you set a media query (using standard CSS syntax) the script will be enabled or disabled automatically depending on whether the query matches or not. This is most useful for elements that should be toggleable at certain screen sizes but always visible at others. (Default: none)

onEnable

A callback that is triggered every time the toggle becomes enabled. You may alternately register an event listener for this purpose – see below. (Default: none)

onDisable

A callback that is triggered every time the toggle becomes disabled. You may alternately register an event listener for this purpose – see below. (Default: none)

onShow

A callback function that will be triggered when the content is displayed. You may alternately register an event listener for this purpose – see below. (Default: none)

onHide

A callback function that will be triggered when the content is hidden. You may alternately register an event listener for this purpose – see below. (Default: none)

Methods

setup()

Activate the toggle control. This happens automatically when you run new accessibleToggle(), but you can also manually recreate it after running the destroy() method.

destroy()

Deactivate the toggle control, removing all aria attributes and behaviors.

show()

Show the content programatically.

const toggle = new Toggle(document.getElementById('navigation'));
toggle.show();

hide()

Hide the content programatically.

toggle.hide();

toggle([display])

Toggle the content between hidden and visible. You may optionally pass true or false to the function to force the content to be shown or hidden.

toggle.toggle();

Events

You may listen for the following custom events on the content element.

toggle-enable

Triggered when the toggle is set up, including when it is recreated due to a breakpoint becoming active.

toggle-disable

Triggered when the toggle becomes inactive, including when it is disabled due to a breakpoint becoming inactive.

toggle-show

Triggered when the content is switched to its visible state.

toggle-hide

Triggered when the content is switched to its hidden state.

Example

import accessibleToggle from 'accessible-toggle';

const navigation = document.getElementById('navigation');
const toggle = new Toggle(navigation, {
  mediaQuery: '(max-width: 600px)',
});

navigation.addEventListener('toggle-show', () => {
  console.log('I am visible now!');
});

Builds

If you don't use a package manager, you can access accessible-toggle via unpkg (CDN), download the source, or point your package manager to the url.

accessible-toggle is compiled as a collection of CommonJS modules & ES2015 modules for bundlers that support the jsnext:main or module field in package.json (Rollup, Webpack 2)

The accessible-toggle package includes precompiled production and development UMD builds in the dist folder. They can be used directly without a bundler and are thus compatible with many popular JavaScript module loaders and environments. You can drop a UMD build as a <script> tag on your page. The UMD builds make accessible-toggle available as a window.accessibleToggle global variable.

Changelog

The project's history is recorded in the Changelog.

License

The code is available under the MIT license.

Contributing

We are open to contributions, see CONTRIBUTING.md for more info.

Thanks

This script was inspired by A11y Toggle.

The project structure was created using generator-module-boilerplate.