11.30.2020

Talking to Screen readers with ARIA-live and Drupal.announce()

neon open sign.

ARIA-live and Drupal.announce(), a11y-friendly JS in Drupal Core.

Drupal.announce is a method built into Drupal core that can make writing accessible code easier.

Why you need it.

If content changes on your site and there’s a visual change to let users know, you also need to make that change clear to folks who can’t see the visual cues – Drupal.announce allows you to do just that.

When should things get announced to a screen reader?

Here’s how to use it:

Add it as a dependency.

In your project’s theme directory, go to the theme.libraries.yml file and add Announce as a dependency.

8[theme].libraries.yml

dependencies:
   - core/drupal.announce

Drupal.announce()

Drupal makes this easy. Use the announce function right in your javascript file at the moment the content or context changes. The screen reader will read the message you pass in, communicating the change and creating a better experience for the user.

Drupal.announce() has a politeness setting, which determines whether the screen reader should read your message update before anything else, or read it in the order in which it appears. The options are ‘polite’ and ‘assertive’. If no value is passed into the function, ‘polite’ is used by default. I recommend using the default polite setting, because manners count – even in code.

Drupal.announce(‘My message’, ‘polite’) is the same as Drupal.announce(‘My message’) If nothing is passed in, the default setting of “polite” is used, which will read the announcement in the order it appears on the page.

Drupal.announce(‘My message’, ‘assertive’’) For updates that should be read immediately, use “assertive”.

Drupal.announce with translations

In your .js file

Drupal.announce(
  Drupal.t("Why, hello there!")
);


How it works

In the browser, you can inspect the code to see the changes. Search for ‘aria-live’ to locate the div at the bottom of the page. When your content changes dynamically, if you added the Drupal.announce function in your javascript file, you should see the message update.

Before the content is updated, the div is empty. You don’t need to add this div, Drupal does it automatically.

<div id="drupal-live-announce" class="visually-hidden" aria-live="polite"
aria-busy="false"></div>

After the Drupal.announce() function runs, the message is inserted.

<div id="drupal-live-announce" class="visually-hidden" aria-live="polite"
aria-busy="false">Tray orientation changed to vertical.</div>

The aria-live div must first be present (and usually empty), so that the browser and assistive technologies(AT) are aware of it. Any subsequent changes are then announced to the user. When Drupal. announce() runs, it updates the contents of the div with the new message, triggering an announcement.

Using ARIA-live without Drupal

This functionality can be added to non-Drupal sites by just adding a div with the aria-live property, hiding it, and using javascript to update the content in the div when you need to communicate a message to the user.

After the Drupal.announce() function ran, the message was updated.

<div class="hide-me" aria-live="polite"></div>

You can also add aria-live="polite" to content on your page that is updated by the user. You can see this on the SPLC hate map. If you select a different state, the number of hate groups changes. This change is announced to the screen reader because the heading has an aria-live property on it.

<h1 id="hate-map-title" aria-live="polite">In 2019, we tracked 940
hate groups across the U.S.</h1>

hate map announcement using aria-live

Resources


Get In Touch

Questions? Comments? We want to know! Drop us a line and let’s start talking.

Learn More
Get In Touch

Related Blog Posts

Fast, Relevant, and Easy to Read

Building a site today is more complex than ever. Front-End developers need to balance the requirements of a design, the tools best suited for implementation, the long-term maintainability of the site by non-developers, and the ever-growing legal risks that can be part of a high-profile client site.

Accessible Cards + Duplicate Links

Card elements are all over the internet -- and so are “Duplicate Link” errors. Here are a few ways to fix these common bugs while tidying up your code at the same time.

Four Questions Your Website Accessibility Statement Should Answer

Your accessibility statement is not just another contact form on your website.