Alert

FeedbackSince 0.2.0

import { Alert } from '@absoluteui/components/alert';
import '@absoluteui/components/alert/style.css';

Using Angular? See Alert for Angular.

What it does

A prominent message block for page- or section-level status. Alert renders a tone icon, a visually hidden localized tone prefix (“Error:”), an optional title, the message, optional action buttons, and an optional dismiss button. Tone is never conveyed by color alone. Alerts are static by default; set live to announce messages that are inserted or changed after the page has loaded.

When to use

• Page- or section-level status that must stay visible until the user reads or dismisses it (for example a failed save or a service notice).
• Messages that offer follow-up actions such as Retry or View details.
• Messages inserted or updated in response to user actions, with live set to ‘polite’ or ‘assertive’.

When not to use

• Short status next to a control or value: use Inline Message.
• Transient confirmation that needs no action: use Toast.
• Field validation errors: use the field’s own error message and the Error Summary.
• Decisions that must block the page: use Dialog (role alertdialog).

Examples

Static service notice

import { Alert } from '@absoluteui/components/alert';

const host = document.createElement('div');
document.body.append(host);
Alert.create(host, {
  tone: 'info',
  title: 'Scheduled maintenance',
  message: 'The service is read-only on Sunday from 02:00 to 04:00 UTC.',
  dismissible: true,
});

Error inserted after a failed save, with Retry

import { Alert, type AlertActionDetail } from '@absoluteui/components/alert';

const host = document.createElement('div');
document.body.append(host);
const alert = Alert.create(host, {
  tone: 'error',
  live: 'assertive',
  title: 'Could not save',
  message: 'Check your connection and try again.',
  actions: [{ label: 'Retry', value: 'retry', variant: 'primary' }],
});
host.addEventListener('aui-action', (event) => {
  if ((event as CustomEvent<AlertActionDetail>).detail.value === 'retry') {
    alert.update({ tone: 'info', title: 'Retrying', message: 'Saving again.' });
  }
});

Usage

import { Alert } from '@absoluteui/components/alert';
import '@absoluteui/components/button/style.css';
import '@absoluteui/components/alert/style.css';

const host = document.querySelector<HTMLElement>('#notice');
if (host) {
  const notice = Alert.create(host, { tone: 'warning', message: 'Your session expires in 5 minutes.', dismissible: true });
  host.addEventListener('aui-dismiss', () => {
    document.querySelector<HTMLElement>('main h1')?.focus();
  });
  notice.update({ title: 'Session ending' });
}

More usage

import { Alert } from '@absoluteui/components/alert';

const host = document.querySelector<HTMLElement>('#save-status');
if (host) {
  Alert.create(host, {
    tone: 'error',
    live: 'assertive',
    title: 'Could not save',
    message: 'Check your connection and try again.',
    actions: [{ label: 'Retry', value: 'retry', variant: 'primary' }],
    dismissible: true,
  });
}

Anatomy

<div class="aui-alert aui-alert--{tone} [aui-alert--dismissible]" [role=status|alert]>
  <span class="aui-alert__icon">icon (aria-hidden)</span>
  <div class="aui-alert__content">
    <span class="aui-alert__tone">Error: (visually hidden)</span>
    <div class="aui-alert__title">title</div>
    <div class="aui-alert__message">message</div>
    <div class="aui-alert__actions">action buttons</div>
  </div>
  <button class="aui-button aui-alert__dismiss" aria-label="Dismiss">icon</button>
</div>

API reference

Factory

Alert.create(host: HTMLElement, options: AlertOptions): Alert

Global configuration key: alert (see Configuration).

Options

Option	Type	Default	Description
message	string | Node		Message; strings render as text. Required.
tone	'info' | 'success' | 'warning' | 'error'	"info"	Tone: icon, colors, and hidden tone prefix.
title	string		Optional title (text).
live	'off' | 'polite' | 'assertive'	"off"	off: static; polite: role=status; assertive: role=alert. Announces content inserted or changed after load.
actions	readonly AlertAction[]		Buttons { label, value, variant? } that emit aui-action.
icons	Partial<AlertIcons>		Icon slot overrides.
dismissible	boolean	false	Render a dismiss button (localized ‘Dismiss’). Globally configurable.
locale	string	"en-US"	Locale of the tone prefix and dismiss label. Globally configurable. Inherited from common configuration.

Properties

Property	Type	Description
host	HTMLElement	The host element (receives role and classes).
isDismissed	boolean	Whether the alert was dismissed (hidden).
options	Readonly<AlertOptions>	Current options.

Methods

Method	Description
update(options: Partial<AlertOptions>): void	Merge and apply options; changed content in a live alert is announced.
dismiss(): boolean	Emit cancelable aui-dismiss, then hide unless prevented. Returns whether it was dismissed.
destroy(): void	Remove rendering, role, classes, and subscriptions.

Events

Event	Detail	Bubbles	Cancelable	Description
aui-action	{ value: string }	Yes	No	An action button was activated.
aui-dismiss	{ reason: 'dismiss-button' | 'programmatic' }	No	Yes	Before the alert hides; preventDefault keeps it visible.

Content areas

Area	Description
message	The message option (string or Node).

CSS classes

All rules live in the aui.components cascade layer, so application styles override them without specificity battles.

Class	Purpose
aui-alert	Host.
aui-alert--info | --success | --warning | --error	Tone modifiers.
aui-alert--dismissible	Has a dismiss button.
aui-alert__icon	Tone icon (decorative).
aui-alert__content	Tone prefix, title, message, and actions.
aui-alert__tone	Visually hidden tone prefix.
aui-alert__title	Title.
aui-alert__message	Message.
aui-alert__actions	Action buttons.
aui-alert__dismiss	Dismiss button.

Icon slots

Slot	Default icon
info	info
success	check-circle
warning	alert-triangle
error	alert-circle
dismiss	close

Design tokens

Tokens this stylesheet reads (verified in CI). Override them in a theme or with the Theme Designer.

--aui-border-width | --aui-border-width-strong | --aui-color-error-fg | --aui-color-error-subtle | --aui-color-info-fg | --aui-color-info-subtle | --aui-color-success-fg | --aui-color-success-subtle | --aui-color-text | --aui-color-warning-fg | --aui-color-warning-subtle | --aui-font-family-sans | --aui-font-size-sm | --aui-font-weight-semibold | --aui-icon-size-md | --aui-line-height-normal | --aui-radius-md | --aui-space-1 | --aui-space-2 | --aui-space-3 | --aui-space-4

TypeScript definitions

type AlertTone = 'info' | 'success' | 'warning' | 'error';
type AlertLive = 'off' | 'polite' | 'assertive';
interface AlertAction { label: string; value: string; variant?: ButtonVariant }
interface AlertIcons { info: IconRef; success: IconRef; warning: IconRef; error: IconRef; dismiss: IconRef }
interface AlertOptions {
  message: string | Node;
  tone?: AlertTone;
  title?: string;
  live?: AlertLive;
  actions?: readonly AlertAction[];
  dismissible?: boolean;
  locale?: string;
  icons?: Partial<AlertIcons>;
}
interface AlertActionDetail { value: string }
interface AlertDismissDetail { reason: 'dismiss-button' | 'programmatic' }

Accessibility

Pattern: WAI-ARIA APG Alert pattern (role=alert) for urgent dynamic messages; role=status for polite updates; plain content when static.

Keyboard

Key	Context	Action
Tab / Shift+Tab	Any	Moves through action buttons, then the dismiss button, in reading order.
Enter / Space	Action button focused	Emits aui-action.
Enter / Space	Dismiss button focused	Emits cancelable aui-dismiss, then hides the alert.

Roles

Element	Role
host	none (live ‘off’), status (live ‘polite’), or alert (live ‘assertive’)
icon	none (aria-hidden=true)
action and dismiss buttons	button (native)

ARIA attributes

Attribute	Element	Value
role	host	status or alert when live is enabled; absent otherwise
aria-label	dismiss button	Localized ‘Dismiss’

Focus

The alert never moves focus. Buttons show their own focus indicator. After dismissal, focus management is up to the consumer (handle aui-dismiss).

WCAG 2.2 success criteria addressed

Criterion	Level	Note
1.3.1 Info and Relationships	A
1.4.1 Use of Color	A
1.4.3 Contrast (Minimum)	AA
1.4.11 Non-text Contrast	AA
2.1.1 Keyboard	A
2.4.7 Focus Visible	AA
4.1.2 Name, Role, Value	A
4.1.3 Status Messages	AA

Automated test results: Accessibility and compliance.

Notes and known caveats

• Tone is conveyed by an icon and a visually hidden, localized prefix such as ‘Error:’, never by color alone.
• Live roles announce only content inserted or changed after the region exists; static page content should use live ‘off’.
• role=alert is assertive and interrupts; reserve it for errors and time-sensitive warnings.
• Manual screen-reader verification (NVDA, JAWS, VoiceOver) is pending.

Behavior

States

info, success, warning, error; with title; with actions; dismissible; dismissed (hidden); live polite; live assertive.

State transitions

From	Trigger	To
visible	Dismiss button / dismiss()	aui-dismiss -> hidden, unless prevented
visible	update({ message })	visible with new content (announced when live)
any	destroy()	host restored to empty

Accessibility notes

• Live roles only announce content inserted or changed after the live region exists. An alert rendered with the initial page is not announced, which is correct for static content. For dynamic messages, insert the host with the alert already rendered (most screen readers announce a role="alert" element when it is inserted), or create it with live set and change it with update().
• Use assertive only for errors and time-sensitive warnings.
• The alert never moves focus. When the user dismisses it with its button, focus would fall to the page; handle aui-dismiss and move focus to a sensible element, such as the heading of the section.
• The e2e axe run (WCAG 2.2 AA, 3 themes) and manual screen-reader verification are pending.

Responsive behavior

Fills its container. Text wraps (overflow-wrap: anywhere), and action buttons wrap onto new lines.

Right-to-left

Logical properties: the icon and the strong tone border are at the inline start, and the dismiss button is at the inline end.

Theming

Each tone uses color-{tone}-subtle for the background, color-{tone}-fg for the icon and border, and color-text for text. All these pairs are in the contrast gate. Forced-colors mode draws CanvasText borders and icons.

Global configuration

configureAbsoluteUI({ components: { alert: { dismissible: true } } });

Component configuration

Instance options override global and theme defaults. dismissible and locale are dynamic: configuration changes re-render existing alerts.

Icons

icons.info (default info), icons.success (check-circle), icons.warning (alert-triangle), icons.error (alert-circle), icons.dismiss (close), resolved through the global icon provider/registry.

Security

Title and string messages use textContent; Node messages are inserted as given, and the consumer owns them. No HTML parsing. The visually hidden prefix is styled through the CSSOM, which is CSP-safe.

Data handling

No persistence, network access, or telemetry. Dismissal is not remembered.

Performance

Constant work per render. Action buttons are rebuilt only when actions changes, so a focused action keeps focus across update() calls.

Supported data scale

Not data-driven.

Edge cases

• Calling dismiss() on an already dismissed alert returns false and emits nothing.
• update() on a dismissed alert updates the content, but the alert stays hidden.
• A Node message is moved into the alert. Pass a new node, or the same node again, to update it.
• Setting live on an alert that is already on the page does not announce the existing content.

Errors

Code	Category	Cause
ALERT_OPTIONS	configuration	Missing or blank message, unknown tone or live value, or invalid action.
ICON_UNKNOWN	configuration	Unknown icon override.
CFG_INVALID_VALUE / CFG_UNKNOWN_OPTION	configuration	Invalid or unknown configuration.

Invalid options throw before the host is modified.

Known limitations

• Focus is not moved after dismissal (see section 15).
• Dismissal is not persisted.
• Manual screen-reader verification is pending.

Unsupported scenarios

• HTML strings as the message: pass a Node instead.
• Automatic timeouts: use Toast.