Alert

Visual Hierarchy

Use variant="default" for informational and success messages. Reserve variant="destructive" for errors and critical warnings so users can quickly distinguish severity. Pair with an icon from Lucide (e.g., Info, AlertCircle, CheckCircle2) to reinforce meaning.

Spacing & Layout

Alerts render as full-width block elements. Constrain width with max-w-xl or similar utilities when placed inside wide containers. Stack multiple alerts with gap-4 for consistent vertical rhythm. Place alerts near the content they relate to rather than at the page top.

Content Structure

Keep titles concise and actionable (e.g., “Payment failed” instead of “There was an error”). Use AlertDescription for supplementary details, recovery steps, or bulleted lists. Omit the description for simple single-line messages where the title is self-explanatory.

Color & Contrast

The default variant uses bg-card with text-card-foreground for a subtle appearance. The destructive variant applies text-destructive to both the title and icon, while the description uses 90% opacity for comfortable reading. Both variants meet WCAG 2.1 AA contrast requirements in light and dark modes.

Keyboard Navigation

• Tab — Alerts are static containers; focus moves through any interactive children (links, buttons) inside the alert
• Enter — Activates any focused interactive element within the alert
• Escape — No default behavior; can be wired to dismiss if implementing a dismissible alert pattern

Screen Reader Support

• Alert renders with role="alert" by default, creating an ARIA live region
• Screen readers announce alert content immediately when it appears in the DOM
• Icons are decorative and should not carry aria-label since the title conveys meaning
• Title and description are semantically grouped within the alert landmark

Live Regions

For alerts injected dynamically (e.g., after form submission), wrap them in a container with aria-live="polite" for non-urgent messages or aria-live="assertive" for critical errors. The built-in role="alert" implies aria-live="assertive" and aria-atomic="true".

Focus Management

Alerts do not trap or steal focus. When an alert appears after a user action, keep focus on the triggering element or move it to the alert only if it contains actionable content. For error alerts in forms, consider moving focus to the first invalid field instead.

ARIA Attributes

{/* Standard alert — role="alert" is built in */}
<Alert>
  <Info className="size-4" />
  <AlertTitle>Information</AlertTitle>
  <AlertDescription>
    Your profile has been updated.
  </AlertDescription>
</Alert>

{/* Live region for dynamic alerts */}
<div aria-live="polite">
  {showAlert && (
    <Alert>
      <CheckCircle2 className="size-4" />
      <AlertTitle>Saved</AlertTitle>
      <AlertDescription>Changes applied successfully.</AlertDescription>
    </Alert>
  )}
</div>

{/* Destructive alert with assertive announcement */}
<div aria-live="assertive">
  {hasError && (
    <Alert variant="destructive">
      <AlertCircle className="size-4" />
      <AlertTitle>Error</AlertTitle>
      <AlertDescription>
        Something went wrong. Please try again.
      </AlertDescription>
    </Alert>
  )}
</div>