Skip to Main Content

Pelican Design System icon Pelican Design System Live Regions

Live Regions

Visual changes in the page need to be communicated to a screen reader.

Edit on GitHub

On this page:

Best Practices

Sighted users can easily detect state changes to a page, such as a list being updated with new items or a javascript-based change of focused element.

  • When something in the page changes visually, it should be announced to screen reader users.
  • Live Regions should be initially empty.
  • Announcements should be meaningful and to the point.
  • Content updates which don’t receive focus will need Live Regions
  • Use assertive politeness value level for immediate updates
  • Use polite politeness value for updates which can wait
  • Live Regions are not visible to sighted users.
  • Only plain string text should go into a Live Region.

Example

Imagine your application has a table with sortable columns.

  1. User presses the column header for “Amount”
  2. Column sorts the values by lowest to highest amount
  3. Live region’s innerHTML would change to “Table sorted by amount, lowest to highest.”
  4. Screen reader would immediately announces the change of the #live-region’s innerHTML.

Be sure to change the example markup for your own project.

Usage

<div id="live-region" aria-live="polite" aria-atomic="true" class="visually-hidden">
    <!-- innerHTML would change -->
    <!-- example -->
    Table sorted by amount, lowest to highest.
    <!-- / example -->
    <!-- change for your use case -->
</div>

Resources

Previous
Next
Page top