Accessibility tools for JavaScript in Drupal 8

Last updated on
17 May 2017

This documentation is out of date. Help make it current.

These tools are under active development in Drupal 8. This documentation page may be out of date

Announce page updates aurally

Many page updates are expressed visually through color changes and animations. In order to make page updates apparent in a non-visual way, Drupal provides the Drupal.announce JavaScript method. This method creates an aria-live element on the page. Text appended to this node is read by a screen-reading user agent.

Drupal.announce accepts a string to be read by an audio UA. You can also set a second parameter: the priority. Here are a couple examples:

Drupal.announce('Entering edit mode');
  Drupal.t('You look beautiful today.')
  Drupal.t('Please fill in your user name'),

Use of Drupal.t() is recommended to ensure announcements are translatable.

The two accepted priority values are polite and assertive. polite is the default.

Assertive statements will interrupt any current speech. Polite statements will not interrupt the user agent. There is a chance they will not be read at all if many things on the page change at once. The announce feature will itself concatenate several calls and read several strings at once to ensure that multiple simultaneous updates are expressed to the end user.

Constrain tabbing

For some interactions, you may want to guide a non-visual user to the most important elements on the page. For example, the Contextual module constrains tabbing to the contextual links when the global edit mode is enabled.

These modules achieve this constrained tabbing with the Drupal.tabbingManager JavaScript feature. To constrain tabbing on the page, invoke the tabbing manager feature like this.

var tabbingContext = Drupal.tabbingManager.constrain($('.contextual-toolbar-tab, .contextual'));

A set of elements is passed to the constrain method. Pressing the tabbing key will now only move between the tab-able elements in this set of elements.

To remove the tabbing constraint, the release method must be called on the tabbing context object.


The Overlay module uses two functions to initiate a tabbing constraint and release the constraint:

 * Makes elements outside the overlay unreachable via the tab key.
Drupal.overlay.constrainTabbing = function ($tabbables) {
  // If a tabset is already active, return without creating a new one.
  if (this.tabset && !this.tabset.isReleased()) {
  // Leave links inside the overlay and toolbars alone.
  this.tabset = Drupal.tabbingManager.constrain($tabbables);
  var self = this;
  $(document).on('drupalOverlayClose.tabbing', function () {

Drupal.overlay.releaseTabbing = function () {
  if (this.tabset) {
    delete this.tabset;

Only one tabbing constraint may be active at a time. If a tabbing constraint is active and another is invoked, the previously active tabbing constraint will be disabled and the new one applied. You need only worry about the tabbing constraint that your module controls.
If another module overrides your tabbing constraint and then releases this constraint, then your module's tabbing constraint will be reapplied. In this case, if your module releases its tabbing constraint while its tabbing constraint is disabled (meaning another module has an active tabbing constraint), then it will not be reapplied, as you would expect.

Devel accessibility

The Devel accessibility (devel_a11y) module was created to aid with implementing, understanding and testing the above accessibility functionality.
It provides browser console logging of announcements and visualization of tabbing constraints.

For example, this is how it helps with visualizing tabbing constraints: