UI Anatomy
ComponentsAlert

Dev view

Alert

An inline non-blocking message that surfaces important information to the user — system status, validation errors, success confirmation, contextual warnings — and announces itself to assistive tech via an `aria-live` region. Distinct from Modal (blocking, demands response), Toast (auto-dismissed, transient), and Tooltip (on-demand description). Alert sits in the document flow, persists until dismissed or the underlying state changes, and may carry optional inline actions.

When to use

Use

When the user must be informed of a system state, validation result, or contextual situation that does not require immediate response — form submission errors, save confirmations, network warnings, system maintenance notices. Alert sits in the document flow, persists until dismissed or the underlying state changes, and announces via aria-live.

Avoid

For decisions or destructive confirmations that block the user — that is `Modal[variant=alertdialog]`. For transient auto-dismissed feedback — that is `Toast`. For on-demand descriptive text — that is `Tooltip`. For permanent informational content (page descriptions, instructions) — that is body prose, not Alert.

Versus related

  • modal

    `Modal[variant=alertdialog]` is a blocking confirmation that demands user response (focus trap + inert siblings). `Alert` is non-blocking and inline; the user may continue working while the alert is visible. Do not confuse the terminology — "alert" the inline message vs "alert dialog" the blocking modal.

  • toast

    `Toast` auto-dismisses after a short visible duration (3–7 seconds canonical); `Alert` persists until the user dismisses or the underlying state changes. Toast is for transient confirmations ("Saved"); Alert is for situations the user may need to revisit or act on.

  • tooltip

    `Tooltip` is on-demand description revealed by hover or focus; `Alert` is system-pushed announcement. Tooltip is pulled by the user; Alert is pushed by the system.

  • banner

    `Banner` is a region-wide persistent informational surface (e.g. a maintenance notice at the top of every page); `Alert` is contextual and tied to a specific situation (a form error, a recent action confirmation). Banner often spans the viewport width; Alert sits within a region.

Highlight
Fig 1.1 · Alert · Dev view
Dev

Code anatomy

Slot Code slot Semantic
container container alert-or-status
icon icon presentational
title title heading-or-strong
body body prose
actions actions button-group
dismiss-button dismiss button
Both

Variants, properties, states

Variants

Structurally different versions of the component.

infosuccesswarningerror

Properties

The same component, parameterised.

PropertyType
dismissibleboolean
hasIconboolean
hasTitleboolean
densitycomfortable | compact

States

Browser/user-driven (interactive) vs. app-driven (data).

KindStates
interactive
hoverfocus-visible
data
openbusydismissed
Both

State transitions

FromToTrigger
openbusyUser activates an action (e.g. Retry). The action handler is in flight; the alert's actions show a busy indicator and become non-activatable. The body and severity remain announced.
busyopenThe action settles (success or failure). On success the consumer typically updates the alert's variant or replaces the alert with a new one; on failure the alert stays in error state with the failure cause appended.
opendismissedUser clicks the dismiss button (when `dismissible: true`). The alert is removed from the document and from the live region; focus moves to the next document focusable unless the alert was the only focusable in its container, in which case focus restores to the trigger that surfaced the alert (rare).
Dev

Cross-framework expression

FrameworkStructure mechanismVariant mechanism
Web Components A `<ui-alert>` host with named slots for `icon` / `title` / `body` / `actions`; `role` reflected from the `severity` attribute (error/warning → alert; info/success → status) attributes (`severity="error"`, `dismissible`, `density="compact"`); `data-state="open|busy|dismissed"` for CSS
React Single `<Alert>` component with `severity` prop driving role; compound subcomponents (`Alert.Icon`, `Alert.Title`, `Alert.Body`, `Alert.Actions`) or named props for content props with class-variance-authority for severity / density; `dismissible` boolean drives close-button visibility plus `onDismiss` callback
Angular (signals) `<ui-alert>` component with content projection (`<ng-content select="[ui-alert-title]">`, `<ng-content select="[ui-alert-actions]">`); host bindings drive `[attr.role]` input<'info' | 'success' | 'warning' | 'error'>(); `[dismissible]`, `[hasIcon]` host bindings; `output('dismiss')`
Vue Single `<Alert>` SFC with named slots for `icon`, `title`, `body`, `actions`; `:severity` prop drives the role defineProps with literal-union types; emits `dismiss`
Both

Events

  1. dismiss
    Payload
    `{ source: 'closeButton' | 'programmatic' }`. Distinguishes a user-clicked dismiss from a consumer-triggered programmatic removal. Programmatic removal does not re-render the alert automatically; consumers manage the alert lifecycle.
    Web Components
    `dismiss` CustomEvent on the host with `event.detail = { source }`.
    React
    `onDismiss(source)` callback. Some libraries pass the original DOM event instead of a discriminated union; consumers wrap to recover the canonical contract.
    Angular Signals
    `output<DismissSource>('dismiss')`.
    Vue
    `@dismiss` event with payload `{ source }`.
  2. actionInvoke
    Payload
    `{ actionId: string }` — the canonical id of the invoked action. The consumer is responsible for executing the action's effect (retrying a request, undoing a change). The alert transitions to `busy` state until the consumer signals completion.
    Web Components
    `actionInvoke` CustomEvent with `event.detail = { actionId }`.
    React
    `onAction(actionId)` callback or per-action `onClick` props on the action slot. The canonical event aggregates per- action handlers into one stream.
    Angular Signals
    `output<string>('actionInvoke')`.
    Vue
    `@action-invoke` event with payload `{ actionId }`.
Dev

Performance thresholds

  • stackDepthvisible-alert-count≥3alerts

    The canonical maximum visible alert count per region is 3. Above this threshold, visual hierarchy collapses and SR announcement floods at page load. Replace stacks of 4+ with a summary alert linking to the full list rendered as a non-live region.

Both

Accessibility

Slot Accessibility hint
container Apply `role="alert"` for assertive severities (error, warning) where the user must attend immediately, or `role="status"` for polite severities (info, success) where the user should be informed but not interrupted. Both roles imply an implicit `aria-live` region; do not stack `aria-live` attributes on top.
icon Decorative — set `aria-hidden="true"` on the icon. Severity is communicated to SR via the `role` (alert vs status) and through the title or body text, never through the icon glyph alone (icon-only severity violates WCAG 1.4.1 Use of Color and 1.3.3 Sensory Characteristics).
title Use a real heading element of an appropriate level when the alert is a top-of-region announcement (e.g. a form error summary). For inline contextual alerts, a `<strong>` or styled `<p>` is sufficient — no heading is required.
body Plain prose. The first user-facing text the SR announces when the alert mounts (after the role is announced). Avoid embedding actions inline — separate actions into the actions slot for keyboard reachability.
actions Buttons keep native semantics. Order primary first (visually inline-end on LTR; SR announces in DOM order). Action buttons receive focus via Tab in document order; the alert does not auto-focus its actions on mount (that would interrupt the user's current task).
dismiss-button Provide an accessible name ("Dismiss alert" or "Dismiss <severity> message"). Activation removes the alert from the live region; SR users do not hear a secondary "alert dismissed" announcement (the silence confirms removal).
Both

Accessibility acceptance

Keyboard walk

KeysExpected
TabFocus moves through the alert in document order: actions first (in DOM order), then the dismiss button. The alert container itself is not focusable; the body is plain prose with no tabindex.
Enter or Space (focus on action button)Activates the action; alert transitions to `busy` while the consumer's handler runs. Focus stays on the action button (or moves to the dismiss button per consumer choice) after settle.
Enter or Space (focus on dismiss button)Dismisses the alert. Focus moves to the next document focusable; if the alert was the only content in its region, focus restores to the trigger that surfaced the alert (rare for inline alerts, common for transient success-after-submit).
Tab (after dismiss)Continues from where focus landed after dismissal. The dismissed alert is removed from DOM; subsequent Tab traverses remaining document focusables.

Screen-reader announcements

TriggerExpected
Alert mounts in a live region (assertive severity)SR interrupts the current announcement and reads the alert's role ("alert") followed by the title (if present) and body. Verbose modes may include the severity word ("Error:" prefix); polite-only modes hear only the body.
Alert mounts in a live region (polite severity)SR queues the announcement after the current one completes — reads the role ("status") followed by title and body. Polite severity does not interrupt.
Alert action invoked, transitions to busyAction button announces busy state via `aria-busy="true"`; SR users hear "<action label>, busy". The alert body text is not re-announced.
Alert dismissedSR users do not hear a secondary "alert dismissed" announcement; the silence (and removal of the live region content) confirms removal. Avoid synthesising a "dismissed" announcement — it adds noise without value.

axe-core rules to assert

  • aria-allowed-role
  • aria-required-attr
  • color-contrast
  • role-img-alt
  • landmark-unique
  • empty-heading
Dev

Common mistakes

#alert-no-aria-live

Alert with no live-region announcement

Problem

The alert renders visually but the role is missing or the element is not in a live region. SR users do not hear the alert; the message is silently delivered to sighted users only.

Fix

Apply `role="alert"` for assertive severities (error, warning) or `role="status"` for polite severities (info, success). Both roles imply an implicit live region — do not stack `aria-live` on top. Test with at least one SR before shipping.

#alert-color-only-severity

Severity differentiated by colour alone

Problem

The alert's severity is communicated only through background or border colour. Colour-vision deficient users cannot distinguish info from error; SR users get no severity cue because the role is the same.

Fix

Triple-layer severity: visual (background + border + severity icon), accessible role (alert vs status), explicit prose ("Error:" prefix or named severity in title). Each layer redundantly communicates severity.

#alert-stacked-without-summary

More than three alerts stacked without summary

Problem

A page accumulates alerts (form validation errors, system messages, user feedback). The stack grows beyond three — visual hierarchy collapses, SR announcement floods at page load, the user cannot prioritise.

Fix

Cap canonical alert stacks at three. Beyond, render a summary alert ("3 errors prevent submission") with a link to the full list rendered as a regular region (not live). Document the threshold in the performance block.

#alert-actions-inside-prose

Alert actions embedded inline in body text

Problem

Body prose contains "Click here to retry" or similar embedded interaction. The interactive element is either an anchor (wrong semantic for an action) or a styled span with a click handler (no semantic at all).

Fix

Move actions to the dedicated actions slot as Button elements. The body describes the situation; actions are separately reachable.

#alert-dismiss-loses-issue

Dismiss removes the issue, not just the alert

Problem

The user dismisses an important warning by accident; the underlying issue (unsaved changes, expired session, network failure) silently persists. The alert was the only signal, and now the signal is gone.

Fix

Distinguish dismiss-the-alert from resolve-the-issue. For warnings of persistent system state, re-render the alert when the user next encounters the affected feature. For transient confirmations, dismissal is final by design. Document the contract per severity: error and warning alerts should not auto-disappear; info and success may.

Figma↔Code mismatches
  1. 01
    Figma

    An alert drawn with severity communicated by background colour alone

    Code

    Severity is reflected via `role` (alert vs status) plus the icon glyph plus the visible severity word in the body

    Consequence

    Designers may rely on Figma's coloured background as the severity differentiator and skip the icon and the explicit severity word. Implementations following the Figma file ship colour-only severity — fails WCAG 1.4.1 (Use of Color) for users with colour-vision deficiencies, and fails for SR users entirely (the role is not implicit in colour).

    Correct

    Severity is communicated through THREE layers: visual treatment (background, border, icon glyph), accessible role (alert vs status), and explicit prose (the body or title text names the severity for SR users).

  2. 02
    Figma

    A dismissible alert drawn with no clear undo affordance

    Code

    An alert with destructive dismissal (the underlying state is also lost)

    Consequence

    Designers draw an "×" close button without considering what dismissal means. Developers ship `onDismiss` that simply removes the alert from the DOM; the user dismisses an important warning by accident, the warning is lost, and the underlying problem persists silently.

    Correct

    Distinguish dismiss-the-alert from dismiss-the-issue. Dismissing the alert is a UI affordance; dismissing the issue requires user action (Retry, Undo). Document both in the actions slot. For warnings of system state, the alert should re-appear when the underlying state next requires attention.

  3. 03
    Figma

    Multiple alerts drawn stacked at the top of a region

    Code

    Multiple alerts stacked dynamically, all wired to live regions

    Consequence

    Designers draw a stack of alerts in mocks; developers ship with each alert in its own live region. SR users hear a torrent of announcements at page load (every alert fires simultaneously); pointer users see a wall of severity treatment competing for attention.

    Correct

    Limit canonical alert stacks to 1–3. Beyond that, replace with a "summary alert" (e.g. "3 errors prevent submission") that links to the full list rendered as a non-live region. Document the canonical maximum in the performance block.

  4. 04
    Figma

    Alert actions drawn as inline links inside the body prose

    Code

    Alert actions as separate button elements in the actions slot

    Consequence

    Designers compose body text with embedded links ("Click here to retry"); developers either ship the literal anchor (link semantics for an action — see Link mistakes) or invent buttons that look like links (visual confusion). Keyboard reachability and SR announcements suffer either way.

    Correct

    Alert actions live in the dedicated actions slot as Button elements (potentially with `variant: tertiary` for visual restraint). Body prose names what the actions do ("Save failed.") without itself being interactive.