This is a script that will handle events related to WAI-ARIA attributes. It's most common use is to bind click events to buttons with the [aria-controls] attribute and to toggle the attribute aria-hidden on it's target. The script acts as a state handler for elements with these attributes. If a aria-controls target changes state, the controlling buttons will reflect that state.
npm install @wezz/ariamanager
import ARIAManager from "@wezz/ariamanager";
// On document ready
new ARIAManager();ARIA Manager is a singleton: every new ARIAManager(...) returns the same
shared instance. You can safely call it from multiple components — they all bind
to one manager, so a control is never bound twice and every controller stays in
sync. (Constructing it on the server is a no-op, so it's safe to import in
server-rendered builds.)
The constructor can take the following options object
const ariaOptions = {
parent: document.body, // Entry point where ARIA Manager queries for relevant elements
initiateElements: true // Set to false to skip the automatic initiation
};
new ARIAManager(ariaOptions);On the shared instance, passing parent simply scopes which elements that call
initialises — it does not create a separate manager.
<button aria-controls="exampletarget1" aria-pressed="false">Open Example target 1</button>
<div id="exampletarget1" class="exampletarget" aria-hidden="true">
</div>If you want to react to something being hidden or visible, the best way is to listen to the internal events being trigged by the ARIAManager.
If a target changes it's aria-hidden state you can use the set-aria-hidden event.
<button aria-controls="eventexample">Toggle</button>
<div id="eventexample" aria-hidden="true">
</div>const target = document.getElementById("eventexample");
target.addEventListener('set-aria-hidden', (e) => {
console.log('New aria-hidden state is', e.detail.value);
});Note that binding to a toggle buttons click event is not recommended when attempting to detect a state.
There can be delays between the click event and that aria attributes are updated
Removing hidden content from the tab order (data-ariamanager-hide)
aria-hidden hides content from the accessibility tree, but focusable children
inside a hidden region stay in the tab order. To also remove them, opt in per
target with data-ariamanager-hide:
<button aria-controls="panel" aria-expanded="false">Toggle</button>
<!-- inert is toggled together with aria-hidden -->
<div id="panel" aria-hidden="true" data-ariamanager-hide="inert" inert>…</div>data-ariamanager-hide="inert"— toggles theinertattribute (keeps layout, best with CSS transitions).data-ariamanager-hide="hidden"— toggles thehiddenattribute (display:none).
Set the initial inert/hidden in markup to match the initial aria-hidden
value. Without the attribute, behaviour is unchanged (aria-only).
Add data-ariamanager-delay (milliseconds) to a control to delay the state
change after a click — useful to let a CSS transition start first.
<button aria-controls="panel" aria-pressed="false" data-ariamanager-delay="150">Toggle</button>The ARIA manager is a class with methods so you can programatically toggle elements visibility and the controlling buttons will reflect the targets state.
const ariaInstance = new ARIAManager();
// This will set the attribute to the target to be _aria-expanded="true"_.
// And any button that targets that element and has the aria-pressed attribute will reflect that state.
ariaInstance.AriaExpand(document.getElementById("exampletarget1"), true); If markup has been added to a page after the ARIA Manager has been updated, it is possible to initialize new elements using a global event against the window.
window.dispatchEvent(new CustomEvent('global-markupchange', { detail: { target: document.querySelector(".additionalDataContainer") } }));The target in the event is optional, but if a target has been added (as a HTML Element) to the detail data; Then the ARIA Manager will only search for new elements to bind to within that container.
The most common usecase is that the ARIA Manager will run on document ready. It is not recommended to use the ARIA Manager within reactive frameworks since the bindings will not re-initialize or get lost when the markup changes.
But if you have a reactive component that use aria-controls attributes on a page that has ARIA Manager, you can add the attribute data-ariamanager-ignore to the aria-controls elements within the reactive component / app to avoid having ARIA Manager adjusting attributes.
Vue Example
<button
aria-controls="myexamplediv"
data-ariamanager-ignore
v-bind:click="this.openState = !this.openState">Toggle</button>
<div id="myexamplediv" v-bind:aria-hidden="(!this.openState)+''">
</div>Look in the example html file for more markup examples on how to use the ARIAManager
ARIAManager mainly works with the direct relation of elements with aria-controls and it's related targets.
There is another manager called ARIATabManager that handles the relationship between multiple elements that manage view states. Use that to easily enable tabbing behavior (close an open area if a sibling is selected).
Adding a aria-hidden attribute and not using it for it's intended use is bad for accessibility.
Elements can be visually visible but hidden for users using screenreaders and more.
The MatchMedia Attribute Manager makes it possible to remove or add aria-hidden depending on a media query.
Use cases can be that you want to show a navigation in desktop, but in mobile it's supposed to be hidden by default and toggled by a button.
See CHANGELOG.md. This project follows Keep a Changelog and Semantic Versioning.
- Move the entries under
## [Unreleased]inCHANGELOG.mdinto a new## [x.y.z] - YYYY-MM-DDsection. - Bump
versioninpackage.jsonto match. - Run
npm run check:exports(publint + are-the-types-wrong). npm publish—prepublishOnlyrebuilds and runspublint, so a package with a brokenexportsmap can't be published.
Clone this repo
Run
npm install
To run the interactive demo, run
npm run demo