Notifications & Dialogs
Alert
AvailableA notification that immediately announces important messages via a live region without moving focus.
What Is an Alert (role="alert")?
An alert is a mechanism for delivering short, important messages such as "Saved successfully" or "There are errors" without interrupting the user's workflow. Toast notifications that appear at the corner of the screen and messages shown after form submission are typical examples.
The key technique is to place a role="alert" region in the DOM ahead of time (initially empty)and later inject the message text via JavaScript. This alone causes screen readers toannounce it automatically. Focus is not moved.
Why Does Accessibility Matter?
Consider users who cannot see -- or have difficulty seeing -- the screen.
- Screen reader users cannot notice a message that simply appears somewhere on the page. With
role="alert", the screen reader interrupts what it was reading to announce the message immediately. - On the other hand, you must not steal focus. Moving focus away from the field a user was editing causes confusion -- they lose their place. An alert "interrupts the announcement" only; the user's position in the page stays where it was.
In other words, role="alert" achieves the ideal balance:the announcement interrupts, but focus does not move.
Live Demo (Recommended Implementation)
Press the button below and a message will appear beneath it. Notice that focus remains on the button.
Try it: Tab to the button, then press Enter to save. Focus stays on the button while the screen reader announces the message.
Tip
Turn on a screen reader (on macOS, press Cmd+F5 for VoiceOver) and press the button. Even though focus does not move, you will hear "Your input has been saved." This is the effect of role="alert" (interrupt announcement).
Keyboard Interaction
| Key | Action | Priority |
|---|---|---|
| (No dedicated key) | The alert itself has no special key interactions. Not moving focus is the correct behavior. | Required |
| Tab | Navigate normally to the trigger (e.g. button) that displays the message. | Required |
Note
An alert is a "passive notification." If you add a close button, make it a regular<button> that is keyboard-operable (do not make the alert region itself focusable).
Required WAI-ARIA Roles and Properties
| Target | Attribute / Role | Meaning |
|---|---|---|
| Notification area container | role="alert" | Makes it an assertive live region. Behaves equivalently to aria-live="assertive". |
| Notification area container | aria-atomic="true" (optional) | When content changes, the entire region is announced as a whole. |
| Container placement timing | (implementation, not an attribute) | Place the container empty in the DOM from the start. Inserting text later triggers announcement. Inserting the entire region later may not be announced. |
Implementation: Recommended Pattern (Good)
Good / Recommended
Place an empty role="alert" region first, then inject only the text later. Do not move focus.
Markup:
<!-- 1. Place an empty notification region in the DOM from the start -->
<div id="status" role="alert"></div>
<button type="button" id="save">Save</button>Injecting the message:
const region = document.getElementById('status');
const button = document.getElementById('save');
button.addEventListener('click', () => {
// 2. When text is injected into a role="alert" region,
// it is automatically announced. Focus stays on the button.
region.textContent = 'Your input has been saved.';
});Note
If you insert the same text consecutively, the announcement may not repeat. You can work around this by appending a counter or by clearing the content before reinserting it, so the screen reader recognizes the content as changed. For non-urgent notifications (e.g., "Auto-saved"), use role="status"(aria-live="polite") instead, which announces without interrupting.
Anti-Pattern (Bad)
The example below is a plain "visual-only banner" with no role or aria-live.Sighted users will see the message, but screen reader users will hear nothing.
Try it: The message appears visually, but the screen reader stays silent. An important notification is completely ignored.
<!-- visual-only banner (no role or aria-live) -->
<button type="button" onclick="showBanner()">Save</button>
<div id="banner" class="banner" style="display:none">
Your input has been saved.
</div>
<!-- Appears on screen, but screen readers are not notified -->Bad / Avoid
Problems with this implementation:
- Not announced -- without
role="alert"oraria-live, the change is not communicated. - Not discoverable -- a screen reader user reading another part of the page will never know the message exists.
- Conversely, stealing focus to force an announcement is also wrong -- it causes users to lose their place.
Tip
The correct approach is to keep focus in place and inject text into a role="alert" region. This respects both announcement and the user's position.
Implementation Checklist
- The role="alert" region is placed empty in the DOM from the start
- Messages are inserted by replacing the text content of the region
- Focus is not stolen when the alert appears
- Non-urgent notifications use role="status" (polite) instead
- Re-notifications of the same text vary the content to ensure announcement
- If a close button is provided, it is keyboard-operable and focus is visible
Source (English):Alert Pattern — W3C APG(opens in a new tab)