Alert

Usage

An Alert is an inline message — it sits inside the flow of the page, next to the form field or panel it describes. Pair a semantic variant with children for the body; add a title when the message benefits from a heading.

import { Alert } from '@epasslive/design-system'

<Alert variant="success" title="Profile updated">
  Your display name and email are now visible to collaborators.
</Alert>

<Alert
  variant="error"
  title="Payment could not be processed"
  dismissible
  onDismiss={() => setShowError(false)}
  dismissLabel={t('common.close')}
>
  Your card was declined. Update your payment method to finish the order.
</Alert>

Alert vs. Banner vs. Notification

Use Alert for short, contextual messages that live inside a form, panel, or card. Use Banner for page-level announcements that span the full width of the layout. Both expose the same four variants — Banner composes the Alert variant contract (ALERT_VARIANT_STYLES) instead of re-declaring its own — but Banner reserves more vertical space and accepts an optional action with its own treatment. For persistent per-user notifications that accumulate in a feed (the bell dropdown), use Notification rows inside a container that owns aria-live="polite" — an Alert is a single inline message in page flow, not a feed item, and an ephemeral auto-dismissing message is a Toast. See the full Alert vs. Toast vs. Notification boundary table on the Notification page.

Alert vs. FormFieldError

Use FormFieldError for validation messages attached to a single form field — it renders inline below the input, wired to the field's aria-invalid state. Use Alert for everything broader: panel-level validation summaries, system messages, and contextual feedback that is not owned by one field. The split is enforced by convention — do not migrate one into the other.

Dismiss behavior

The dismiss button is only rendered when both dismissible is true and onDismiss is a function. The parent owns the visible state — the component does not unmount itself. Pass dismissLabel for i18n parity; the same label is exposed via aria-label on the button.

Accessibility

The root element carries role="alert" with aria-live="assertive" for the error variant, and role="status" with aria-live="polite" for success, warning, and info. When a title is set, the heading is wired to the root via aria-labelledby. Icons are decorative (aria-hidden) — announcement is owned by the role + aria-live pair. The variant is mirrored to data-variant for end-to-end testing.

Dark mode

Alert supports light and dark themes through the ADR-027 semantic token family: each variant has a dedicated --ep-semantic-{success,warning,error,info}-tint background, -fg foreground, and -tint-border border, with light and dark values tuned so text meets WCAG AA (≥4.5:1) on its own tint in both themes (Tailwind: bg-ep-semantic-success-tint, text-ep-semantic-success-fg, border-ep-semantic-success-tint-border). When styling custom alert-like surfaces, consume these theme-tuned token pairs rather than layering /10-alpha variants of the raw accent tokens — alpha transparency over the page background does not hold contrast in both themes, and some alpha steps are not registered for every accent (ghost utilities).

Props