Live Region

Headless Live Region; covers ARIA live regions, WAI-ARIA status and alert.


Package	`@vizejs/ui/live-region`
Maturity	stable
Own the source	`vize lib pull live-region`
Requires	—
Aliases	announcer, aria live, status region
Covers	ARIA live regions, WAI-ARIA status and alert

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/ui

Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.

import { LiveRegion } from "@vizejs/ui/live-region";

Or copy the source into your project with vize lib pull live-region (see Source Distribution).

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Polite live region that announces when an item is added to the cart. -->
<script setup lang="ts">
import { ref, useTemplateRef } from "vue";

import { LiveRegion } from "@vizejs/ui/live-region";

const region = useTemplateRef<InstanceType<typeof LiveRegion>>("region");
const count = ref(0);

function addToCart(): void {
  count.value += 1;
  region.value?.announce(`Added to cart. ${count.value} items in your cart.`);
}
</script>

<template>
  <div>
    <button type="button" @click="addToCart">Add notebook to cart</button>
    <LiveRegion ref="region" />
  </div>
</template>

API

`LiveRegion`

Source: src/families/accessibility/live-region/live-region.vue

Props

Prop	Type	Default	Description
`politeness`	`LiveRegionPoliteness`	`"polite"`	Default announcement urgency.
`atomic`	`boolean`	`true`	Whether assistive technology should present the whole region on each update.

Slots

Slot	Slot props	Description
`default`	—	Optional visible contents rendered alongside the announcer text.

Exposed

Member	Type	Description
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`announce`	—
`clear`	—
`message`	—

Behavior

Normative state × input → outcome table for live-region.vue (@vizejs/ui/live-region). Every row is proven by the named test in src/families/accessibility/live-region/live-region.test.ts or src/families/accessibility/live-region/live-region-ssr.test.ts; compile-only assertions live in src/families/accessibility/live-region/live-region.types.test-d.ts.

#	State	Input	Outcome	Proven by
L1	idle	render	polite status region is empty	`renders an empty polite live region`
L2	idle	`announce`	message is published after a clear tick	`announces text after clearing`
L3	announced	identical `announce`	text is re-announced by clearing first	`announces text after clearing`
L4	idle	assertive politeness	role is `alert` and `aria-live` is assertive	`switches to an assertive alert region`
L5	announced	`clear`	message is emptied	`clears the current announcement`
L6	any	render	exposed `element` is the rendered node	`exposes the rendered element for composition`
L7	SSR	default render	byte-identical empty polite region	SSR test
L8	public types	invalid politeness	compilation rejects misuse	`src/families/accessibility/live-region/live-region.types.test-d.ts`