accessible-toggle v1.3.1
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.