Announcement
ARIA live-region wrapper with no visual output. Announces dynamic content changes to screen readers.
<arc-announcement>Overview
Announcement is an accessibility utility that creates an ARIA live region for announcing dynamic content changes to screen readers. It has no visual output (zero width, zero height) and exists only for assistive technology users.
When you set the message property, the component updates its internal live region and the screen reader announces the new content. The politeness prop controls the interruption level: polite waits for the screen reader to finish its current announcement before speaking the new message, while assertive interrupts immediately for urgent updates.
Use announcement for any dynamic state change that sighted users can perceive visually but screen reader users would otherwise miss: route changes, live search result counts, form submission confirmations, timer updates, or chat message arrivals. Place the component once in your layout and update its message property whenever you need to announce something.
Guidelines
When to use
- Use announcement for dynamic content changes that screen reader users would otherwise miss
- Use polite for non-urgent updates like search result counts or status changes
- Use assertive for critical updates like errors, timeouts, or session expiration warnings
- Place a single <arc-announcement> in your layout and reuse it for all announcements
- Keep messages concise; screen reader users cannot skim long announcements
When not to use
- Do not use announcement for content that is already in an ARIA live region (like toast or alert)
- Do not fire rapid successive announcements; screen readers may drop intermediate messages
- Do not use assertive for routine updates. It interrupts the user and should be reserved for urgency
- Do not duplicate announcements that are already handled by native ARIA roles
- Do not use announcement as a substitute for proper labeling and semantic HTML
Features
- ARIA live region with configurable politeness (polite or assertive)
- No visual footprint: no width, height, or visible rendering
- Set the message property to trigger a screen-reader announcement
- Polite mode waits for current speech to finish before announcing
- Assertive mode interrupts current speech for urgent updates
- Each message change triggers a new announcement
- Renders a single visually-hidden element
- Works with all major screen readers (NVDA, JAWS, VoiceOver, TalkBack)
Preview
Usage
<script type="module" src="@arclux/arc-ui"></script>
<arc-announcement id="announcer" politeness="polite"></arc-announcement>
<arc-button onclick="document.getElementById('announcer').message = '42 results found.'">
Search
</arc-button>import { Announcement, Button } from '@arclux/arc-ui-react';
import type { ArcAnnouncement } from '@arclux/arc-ui/announcement';
import { useRef } from 'react';
export function SearchDemo() {
// Typing the ref as ArcAnnouncement is what makes `message` visible to
// TypeScript — an HTMLElement has no such property.
const announcerRef = useRef<ArcAnnouncement>(null);
const handleSearch = () => {
// perform search...
if (announcerRef.current) {
announcerRef.current.message = '42 results found.';
}
};
return (
<>
<Announcement ref={announcerRef} politeness="polite" />
<Button onClick={handleSearch}>Search</Button>
</>
);
}<script setup>
import { ref } from 'vue';
import { Announcement, Button } from '@arclux/arc-ui-vue';
const announcer = ref(null);
const handleSearch = () => {
if (announcer.value) announcer.value.message = '42 results found.';
};
</script>
<template>
<Announcement ref="announcer" politeness="polite" />
<Button @click="handleSearch">Search</Button>
</template><script>
import { Announcement, Button } from '@arclux/arc-ui-svelte';
let announcer;
const handleSearch = () => {
if (announcer) announcer.message = '42 results found.';
};
</script>
<Announcement bind:this={announcer} politeness="polite" />
<Button on:click={handleSearch}>Search</Button>import { Component, ViewChild, ElementRef } from '@angular/core';
import { Announcement, Button } from '@arclux/arc-ui-angular';
@Component({
imports: [Announcement, Button],
template: `
<arc-announcement #announcer politeness="polite"></arc-announcement>
<arc-button (click)="handleSearch()">Search</arc-button>
`,
})
export class SearchDemoComponent {
@ViewChild('announcer') announcer!: ElementRef;
handleSearch() {
this.announcer.nativeElement.message = '42 results found.';
}
}import { Announcement, Button } from '@arclux/arc-ui-solid';
import type { ArcAnnouncement } from '@arclux/arc-ui/announcement';
export function SearchDemo() {
let announcer: ArcAnnouncement | undefined;
const handleSearch = () => {
if (announcer) announcer.message = '42 results found.';
};
return (
<>
<Announcement ref={announcer} politeness="polite" />
<Button onClick={handleSearch}>Search</Button>
</>
);
}import { Announcement, Button } from '@arclux/arc-ui-preact';
import type { ArcAnnouncement } from '@arclux/arc-ui/announcement';
import { useRef } from 'preact/hooks';
export function SearchDemo() {
const announcerRef = useRef<ArcAnnouncement>(null);
const handleSearch = () => {
if (announcerRef.current) {
announcerRef.current.message = '42 results found.';
}
};
return (
<>
<Announcement ref={announcerRef} politeness="polite" />
<Button onClick={handleSearch}>Search</Button>
</>
);
}<!-- Auto-generated by @arclux/prism — do not edit manually -->
<!-- arc-announcement — requires announcement.css + base.css (or arc-ui.css) -->
<div class="arc-announcement">
<div role="status" aria-live="polite" aria-atomic="true">Message</div>
</div><!-- Auto-generated by @arclux/prism — do not edit manually -->
<!-- arc-announcement — self-contained, no external CSS needed -->
<div class="arc-announcement" style="position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0,0,0,0); clip-path: inset(50%); white-space: nowrap">
<div role="status" aria-live="polite" aria-atomic="true">Message</div>
</div>API
messagestring''- The text to announce to screen readers. Each time this property changes, a new announcement is triggered.
politeness'polite' | 'assertive''polite'- Controls the ARIA live region politeness level. Polite waits for the screen reader to finish before announcing; assertive interrupts immediately.