LiveRegion

Components/Feedback

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/liveregion

Overview

Copy

Live region is a mechanism that broadcasts a message for screen reader users to inform them about the change in the page layout or the status.

Do

  • Use it to inform users with visual impairments about change in page content
  • Use it to inform users with visual impairments about page status change without moving users' focus

Don't

  • Don't use it when triggered action moves user focus to another element, for example to a newly created item. Use <LiveRegion/> when user focus remains where it is, but users must be aware of the changes that happened on the page.
  • Don't use it to announce the opening of menus, modals or notifications. These types of announcements are a built-in definition of components.
  • Don't use it to announce dynamic content that's not critical. Avoid adding unnecessary noise for assistive technologies.

Feature examples

Broadcast

Specify a message to announce for screen reader users with broadcast prop.

Copy

Role

Specify how urgently a message should be broadcasted with role prop.

There are 2 roles types:

  • status (default) - use it when it's important that user receives updates about changes in the region, but not so rapidly that natural flow would be interrupted. Screen reader will announce a message after the current message is delivered.
  • alert - use for time sensitive and critical notifications that require immediate users attention. Message will be announced right away, even if screen reader is currently in the middle of a sentence. As such, it can be disruptive and should be used sparingly.
Copy

Common use case examples

Remove item

Use live region to inform screen reader users about items removed from the page.

Copy

Duplicate item

Use live region to inform screen reader users about duplicated items added to the page.

Copy

Filter Table

Use live region to inform users about the number of items that match their filter criteria.

Copy

Code

Copy

Props

NameTypeDefaultDescription
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
refnull | string | (instance: LiveRegionRefType | null) => void | RefObject<LiveRegionRefType>—Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref).

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
existsChecks whether the component found with the given data hook
elementGets the component root element
getMessageReturns the message
getRoleReturns the role
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.320.0 (2026-09-03) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.119.0 (2024-07-31) — fix: adjusting position so it wouldn't affect layout (#14002)
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.104.1 (2024-05-14) — maintenance release, no component-specific changes
  • 1.101.0 (2024-04-12) — fix: reverting LiveRegion NVDA screen reader regression (#13545)
  • 1.98.0 (2024-03-15) — maintenance release, no component-specific changes
  • 1.97.2 (2024-03-04) — fix: live region now supports announcing same message multiple times (#13406)
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?