useLiveAnnouncer

Category

Browser

Export Size

Last Changed

last month

Accessible way to announce messages to screen reader users (ARIA live regions).

Demo

sourceplayground (beta)

Click the buttons below to trigger screen reader announcements.

Note: You need a screen reader active to hear the announcements.

Usage

import { useLiveAnnouncer } from '@vueuse/core'

const { announce, polite, assertive } = useLiveAnnouncer()

announce('This is a polite announcement')
polite('This is also a polite announcement')
assertive('Important message!')

The message stays in the live region until it is replaced by the next announcement. Pass a timeout (in milliseconds) to automatically clear it after a delay:

TypeScript

// clears the message after 3000ms
announce('Saved successfully', 'polite', 3000)
polite('Saved successfully', 3000)
assertive('Network error', 3000)

'use strict'
// clears the message after 3000ms
announce('Saved successfully', 'polite', 3000)
polite('Saved successfully', 3000)
assertive('Network error', 3000)

Accessibility

The announcer uses the following ARIA attributes:

• Polite: role="status", aria-live="polite", aria-atomic="true"
• Assertive: role="alert", aria-live="assertive", aria-atomic="true"

These ensure robust support across different screen readers.

Options

idPrefix

• Type: string
• Default: 'vueuse-live-announcer'

Prefix for the id of the announcer elements. The generated elements will have IDs ${idPrefix}-container, ${idPrefix}-polite, and ${idPrefix}-assertive.

window

• Type: Window
• Default: defaultWindow

The window object where the announcer elements will be created.

Type Declarations

export interface UseLiveAnnouncerOptions extends ConfigurableWindow {
  /**
   * The prefix for the id of the announcer elements.
   * @default 'vueuse-live-announcer'
   */
  idPrefix?: string
}
export interface UseLiveAnnouncerReturn {
  announce: (
    message: string,
    mode?: "polite" | "assertive",
    timeout?: number,
  ) => void
  polite: (message: string, timeout?: number) => void
  assertive: (message: string, timeout?: number) => void
}
export declare function useLiveAnnouncer(
  options?: UseLiveAnnouncerOptions,
): UseLiveAnnouncerReturn

Source

Source • Demo • Docs

Contributors

IceMooncake

Changelog

Pending for release...

4ed28 - feat: new function (#5315)