Alerts are dynamic content that is injected into the page when it changes and a person using a screenreader needs to know that some state of the application has changed.

  • Use alerts sparingly.
  • If an alert is present on page load, it won’t be read automatically
    • If an element is present on page load, it is not technically an alert
  • The alert will be read by the screen reader when it becomes visible / appears in the DOM

Code examples

Basic notification

<div role="alert" 
     class="alert notification inert">
    <!--- Use JS to inject the alert here -->

<button id="show-alert-notification">
  Save my settings

Error alert from an input field

<label for="favorite-nato-letter">
  What is your favorite NATO letter?
<div class="hint" id="favorite-nato-hint">
  Example: Alpha, Bravo, Charlie
<div role="alert" 
     class="alert inert">
  <!--- Do not reference this alert element
        directly with aria-describedby -->
  <div id="favorite-nato-error">
    <!--- Use JS to inject the alert here -->
<input type="text"
       aria-describedby="favorite-nato-error favorite-nato-hint"
<button id="show-error">
  Toggle error
Example: Alpha, Bravo, Charlie

Developer notes

Browser + screenreader quirks

  • Screenreaders do not implement alerts uniformly and must be tested
    • Just because an alert pattern works in one screenreader doesn’t mean it will work in all three
  • The element referenced by the aria-describedby attribute cannot use the role="alert" attribute (see example above for workaround).
  • NVDA will read the alert twice if it appears while the input is in focus: once from the role="alert" being injected and from the aria-describedby association.
  • NVDA needs a fraction of a second to catch up with changes in the DOM, use a setTimeout to delay displaying the alert


  • Inner text describes alert when it appears on screen


  • Use role="alert" for elements injected into the page


  • Focus does move to the element when the alert appears

Design notes

  • Perceivable
    • Type size is no smaller than 16px
    • The text has a 4.5:1 minimum contrast ratio
    • Color is not used as the only means of conveying information
  • Operable
    • The clickable/tappable target areas are no smaller than 44x44px
    • The focus indication has a minimum area equal to the width of the element and 2px in height
    • The focus state has a 3:1 minimum contrast ratio between the default and focused states
    • The focus indication has a 3:1 minimum contrast ratio against adjacent elements
  • Understandable
    • The alert purpose should be clear in the context of the whole page
  • Robust
    • Meets criteria across platforms, devices and viewports

Related alert notification entries