Announcement
ARIA live-region wrapper with no visual output. Announces dynamic content changes to screen readers. Zero visual footprint — pure accessibility utility.
<arc-announcement> Overview
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)
- Zero 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
- Supports dynamic message updates — each change triggers a new announcement
- Lightweight — 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 { useRef } from 'react';
export function SearchDemo() {
const announcerRef = useRef<HTMLElement>(null);
const handleSearch = () => {
// perform search...
if (announcerRef.current) {
(announcerRef.current as any).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';
export function SearchDemo() {
let announcer: HTMLElement | undefined;
const handleSearch = () => {
if (announcer) (announcer as any).message = '42 results found.';
};
return (
<>
<Announcement ref={announcer} politeness="polite" />
<Button onClick={handleSearch}>Search</Button>
</>
);
}import { Announcement, Button } from '@arclux/arc-ui-preact';
import { useRef } from 'preact/hooks';
export function SearchDemo() {
const announcerRef = useRef<HTMLElement>(null);
const handleSearch = () => {
if (announcerRef.current) {
(announcerRef.current as any).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
-
politeness'polite' | 'assertive''polite' - Controls the ARIA live region politeness level. Polite waits for the screen reader to finish before announcing; assertive interrupts immediately.
-
messagestring'' - The text to announce to screen readers. Each time this property changes, a new announcement is triggered.