LiveRegion

Purpose

A region that announces a message that appeared after an action. What decides whether a screen reader says a status message is the document a second earlier: a region created with its text is not restituted by every reader. This component is the region, present and empty from the first render, whose text the page changes.

When to use, when not

Use it for the outcome of an action that does not move the focus: saved, failed, three results found, copied. Do not use it for a message that takes the focus (an error summary is not a status message), for a message present at load (nothing to announce), or as a second announcement of something a control already says, such as a checked radio.

Anatomy

1. A div with role="status" or role="alert" and the matching aria-live.
2. The message, or nothing.

Props

Props of LiveRegion

Name	Type	Default	What it does
message?	string	''	The text to announce. Empty at first; a change is what gets announced, so a message repeated verbatim says nothing and should vary.
tone?	'polite' | 'assertive'	'polite'	`polite` waits for a pause; `assertive` interrupts and is for an error that blocks.
visible?	boolean	false	Show the message as text; hidden by default, the page shows the outcome its own way.
class?	string	''	Layout classes only.

States

Polite, assertive, and hidden.

assertive

role alert, announced at once: for an error that blocks, nothing else.

Light

Simuler un échec

Dark

Simuler un échec

320 px, light

Simuler un échec

320 px, dark

Simuler un échec

216 px, light

Simuler un échec

Forced colours, captured

hidden

The default: the page shows the outcome its own way and the region only says it.

Light

Marquer comme lu

Dark

Marquer comme lu

320 px, light

Marquer comme lu

320 px, dark

Marquer comme lu

216 px, light

Marquer comme lu

Forced colours, captured

polite

role status, announced at the next pause. The region is in the document from the first render, empty.

Light

Enregistrer l'audit

Dark

Enregistrer l'audit

320 px, light

Enregistrer l'audit

320 px, dark

Enregistrer l'audit

216 px, light

Enregistrer l'audit

Forced colours, captured

Accessibility contract

• Role and name: status with aria-live="polite" for the ordinary case, alert with assertive for an error that blocks. No name: a live region announces its content.
• Keyboard, focus: none. A live region never moves the focus, that is what makes it one.
• Live regions: this is one. It exists from the first render; the page never mounts it at the moment of the announcement. A text identical to the previous one is not a change and announces nothing: a repeated outcome must vary, by a count or a time.

Content rules

French. A message is one sentence that says what happened: “Audit enregistré.”, “Trois pages correspondent.”, “Échec de l’enregistrement : la connexion a été perdue.” An error says what to do next when there is something to do.

Do and don’t

• Do mount the region with the page and change message; never {#if message} around it.
• Do use assertive for an error that blocks the user, and for nothing else; an assertive success harasses.
• Do not announce what a control already says: a checked radio, a pressed toggle.

Examples

<LiveRegion message={outcome} />
<Button onclick={async () => { await save(); outcome = `Audit enregistré à ${time()}.`; }}>Enregistrer</Button>

Surfaces

• App: the dashboard’s filter count, the audited page’s saved comment, the report’s export; the form outcomes are Alerts that say they are live.
• Extension: one region per screen, mounted at boot, for the announcements the panel makes today by redrawing an aria-live main.

Related

Alert, Field.

Decisions

• 2026-09-24: a region, not a function. An announce() helper that mounts a region on demand is the anti-pattern this component exists to prevent; the page owns a region and writes to it.
• 2026-09-24: hidden by default. The page usually shows the outcome its own way; a visible region is for the cases where the region is the text, as in the stories.

Criteria held by construction

• 7.5, Dans chaque page web, les messages de statut sont-ils correctement restitués par les technologies d'assistance ?
  The region is in the document from the first render, empty, and only its text changes: that is the one shape every screen reader restitutes, and the component makes the other shapes impossible.
• 7.1, Chaque script est-il, si nécessaire, compatible avec les technologies d'assistance ?
  The role is chosen from the tone, status or alert, and aria-live is written with it, so the announcement is compatible with the readers that honour one or the other.

Tokens it reads

• Colour: --rl-ink
• Typography: --rl-text-sm
• Spacing: --rl-space-3