<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
- Use announcement for content that is already in an ARIA live region (like toast or alert)
- Fire rapid successive announcements — screen readers may drop intermediate messages
- Use assertive for routine updates — it interrupts the user and should be reserved for urgency
- Duplicate announcements that are already handled by native ARIA roles
- Use announcement as a substitute for proper labelling 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: `
<Announcement #announcer politeness="polite"></Announcement>
<Button (click)="handleSearch()">Search</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>
</>
);
}<!-- See HTML tab after running pnpm generate -->
<div class="arc-announcement" aria-live="polite">...</div><!-- See HTML (Inline) tab after running pnpm generate -->
<div class="arc-announcement" style="..." aria-live="polite">...</div>API
| Prop | Type | Default | Description |
|---|---|---|---|
politeness | 'polite' | 'assertive' | 'polite' | Controls the ARIA live region politeness level. Polite waits for the screen reader to finish before announcing; assertive interrupts immediately. |
message | string | '' | The text to announce to screen readers. Each time this property changes, a new announcement is triggered. |