Change record status: 
Introduced in branch: 

In Drupal 8, we provide a simple way to turn text into speech.


The Drupal.announce() function was first brought up at the Drupal Camp Toronto accessibility sprint in the fall of 2012. We need a way to express changes in the state of the toolbar that could not be described with existing ARIA state markup. An example is whether or not a toolbar tray is open when a tab in the toolbar is toggled.

It quickly became obvious that many modules in Drupal would benefit from a system that could read arbitrary strings through the screen reader.

When to use

Whenever something on the page changes dynamically. For example: scrolling causes additional content to be loaded. The changes are communicated visually, but for a screenreader user, it is impossible to know that this happened. It's impossible to express this through ARIA attributes.
The aria-live attribute:

Indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region.

In other words: "whatever text you set within such an element, it will be read by the screen reader".

Rather than having each module create such an element, and each module solve the same problems repeatedly (e.g. what if announcements are made in quick succession or in parallel?), we consolidated all that in Drupal.announce()

How to use

// Pass a string.
Drupal.announce('The application has been updated.');
// Make sure the string is translatable.
  Drupal.t('The application has been updated.')

Not familiar with screen readers?

Use the devel_a11y module to see in your web browser's console what would have been spoken.

Module developers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other updates done