ARIA Live Regions in Drupal 11: What Core Does, What You Add

Drupal 11's server-rendered message templates give errors a role="alert" and nothing else — warnings, status and info messages leave the template with no live-region semantics at all, and closing that gap takes one template override. Core's JavaScript messages API is the exception: it already announces every message and sets the role for you, so the work is narrower than the usual advice suggests.

That first sentence is not the usual framing. Most guides start from "Drupal messages are invisible to screen readers", which is not what the code says. Before writing this I read every status-messages.html.twig shipped in Drupal 11.4.6, and the picture is more specific and more useful than the scare version.

What Drupal core actually does today

Every core template — the system default, Olivero, Claro, Stable 9 and Starterkit — follows the same shape:

• The wrapper gets role="contentinfo" and an aria-label taken from the status heading.
• A visually hidden <h2> names the message type, so heading navigation reaches it.
• When and only when type == 'error', an inner element gets role="alert".

Under the ARIA specification, role="alert" carries an implicit aria-live="assertive" and aria-atomic="true". So errors are announced. That is genuinely handled.

What is not handled: no core template sets an explicit aria-live attribute anywhere, and warnings, status and info messages get no role="alert", no role="status" and no live region. A "Your changes have been saved" confirmation is, for a screen reader user on stock Drupal, silent. So is a warning.

One more thing worth knowing before you copy a template: Drupal 11's default_admin theme drops the role="alert" wrapper entirely, so on that theme even errors are silent. Check the template your theme actually inherits rather than assuming the core default.

The other half core already gives you: Drupal.announce()

Core ships core/misc/announce.js, exposed as the core/drupal.announce library. On attach it creates a single element:

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

Any JavaScript can push text into it with Drupal.announce('Saved', 'polite'). This is the sanctioned way to announce something that is not a rendered status message — an AJAX result count, a filter that narrowed a list, a step that completed. Reach for it before you invent a second live region.

Why the gap matters

WCAG 2.1 Level AA, Success Criterion 4.1.3 Status Messages, requires that a status message be programmatically determinable through role or properties, so assistive technology can present it without the user having to move focus to it. A saved-confirmation with no role and no live region does not meet that. Neither does a warning.

The practical consequence is narrower than the usual statistics suggest, and worth stating honestly: this affects people using a screen reader. It matters most where a message is the only feedback a user gets — a form that reloads with a warning, an AJAX filter that returns nothing, a checkout step that half-succeeded. Public sector procurement in the EU and the US treats 4.1.3 as in scope, so on a government or education build this is a compliance line item, not a nicety.

Choosing assertive or polite

Assertive interrupts whatever is being read. Polite waits for a pause. The failure mode of over-using assertive is a page that talks over itself, which users switch off — so reserve it for messages that block progress.

The template override

Copy your theme's status-messages.html.twig into themes/custom/YOUR_THEME/templates/misc/ and set the attributes from the message type:

{% for type, messages in message_list %}
  {% set is_critical = type in ['error', 'warning'] %}
  {% set msg_attributes = create_attribute()
    .addClass(['messages', 'messages--' ~ type])
    .setAttribute('data-drupal-selector', 'messages')
    .setAttribute('role', is_critical ? 'alert' : 'status')
    .setAttribute('aria-live', is_critical ? 'assertive' : 'polite')
    .setAttribute('aria-atomic', 'true')
  %}
  <div{{ msg_attributes }}>
    {% if status_headings[type] %}
      <h2 class="visually-hidden">{{ status_headings[type] }}</h2>
    {% endif %}
    {% if messages|length > 1 %}
      <ul>{% for message in messages %}<li>{{ message }}</li>{% endfor %}</ul>
    {% else %}
      {{ messages|first }}
    {% endif %}
  </div>
{% endfor %}

aria-atomic="true" is the attribute people forget. Without it a screen reader may announce only the part of the region that changed, so the user hears a fragment instead of the sentence.

Theming work like this is where a lot of accessibility debt actually lives — how you organise theme CSS decides whether anyone can find the override six months later. If you would rather this were built and tested rather than described, that is Drupal theming work.

The behaviour for messages the template never sees

Templates cover server-rendered messages. AJAX callbacks and contrib modules can inject markup afterwards. A small behaviour catches those without fighting the template:

(function (Drupal, once) {
  'use strict';

  const liveByType = { error: 'assertive', warning: 'assertive' };

  const typeOf = (el) =>
    ['error', 'warning', 'status', 'info']
      .find((t) => el.classList.contains(`messages--${t}`)) || 'status';

  Drupal.behaviors.messageAccessibility = {
    attach(context) {
      once('message-a11y', '[data-drupal-selector="messages"]', context)
        .forEach((el) => {
          const type = typeOf(el);
          if (!el.hasAttribute('role')) {
            el.setAttribute('role', liveByType[type] ? 'alert' : 'status');
          }
          if (!el.hasAttribute('aria-live')) {
            el.setAttribute('aria-live', liveByType[type] || 'polite');
          }
          if (!el.hasAttribute('aria-atomic')) {
            el.setAttribute('aria-atomic', 'true');
          }
        });
    },
  };
})(Drupal, once);

Every write is guarded by hasAttribute. That guard is the difference between an enhancement and a regression: without it, JavaScript quietly downgrades the assertive error your template just set. Declare it against core/drupal and core/once — once is a real core library, version 1.0.1 in Drupal 11.4.6.

Testing it, because markup validation is not testing

Correct attributes and a good announcement are different things, and only one of them shows up in DevTools.

• NVDA on Windows — free from nvaccess.org. Submit an empty required form; the error should cut in immediately. Save a setting; the confirmation should wait for a pause.
• VoiceOver on macOS — built in, Cmd+F5. It handles live regions differently from NVDA, which is exactly why you test both.
• axe DevTools — catches missing and invalid ARIA attributes. It cannot tell you whether an announcement was heard.

Test the AJAX path specifically. That is where template-only implementations fall over, and it is the path a real user hits most.

Common questions

Does Drupal 11 handle this out of the box?

Partly. Errors get role="alert" in every core theme except default_admin. Warnings, status and info messages get nothing.

If role="alert" already implies assertive, why set aria-live too?

Because it is explicit and costs nothing. Some assistive technology combinations have historically been more reliable with both present, and it makes the intent readable to the next developer.

Should I use aria-live or Drupal.announce()?

Both, for different jobs. Live-region attributes on the message container for rendered messages; Drupal.announce() for anything JavaScript needs to say that is not a status message.

Will making all messages assertive be safer?

No. Assertive interrupts. A page where every confirmation talks over the user is one they stop using assistive technology on, which is a worse outcome than a missed confirmation.

My messages auto-dismiss after a few seconds. Is that a problem?

Yes, if the element is removed before the announcement completes. Either keep messages until dismissed, or leave a generous delay — and verify with a real screen reader rather than a stopwatch.

Where to take this next

Message announcement is one criterion. If you are working through WCAG on a Drupal build, the same "check what core already does before overriding it" method applies to landmarks, headings and block titles — hidden block titles is the next one that usually bites.

If you need this implemented and evidenced on a real build — public sector, education, anything where 4.1.3 has to be defensible — Drupal theming and Drupal services both cover it, and a short conversation is usually enough to tell which one you need.