Alert

A callout for important contextual messages. Composes AlertTitle, AlertDescription, and an optional AlertAction for dismissal or follow-up actions. Uses role="alert" for screen reader announcements.

Anatomy

<Alert> is a grid container with data-slot="alert" and a prominent left border. An SVG icon child automatically shifts title and description to a second column. AlertAction is absolutely positioned top-right.

Alert Title

Alert description text providing supporting detail.

data-slot="alert"role="alert"SVG shifts to col 1AlertAction → absolute top-right

Variants

Two variants communicate intent through color and border styling.

variant="default"

Information

Your session will expire in 30 minutes. Save your work to avoid losing changes.

variant="destructive"

Payment failed

Your card was declined. Please update your payment method to continue.

With Action

AlertAction renders absolutely at the top-right corner. Use it for dismiss buttons or compact follow-up CTAs.

Dismissible

New feature available

Keyboard shortcuts are now available. Press ? to view them.

With CTA

CLI update available

Version 2.1.0 is available with performance improvements.

States

No icon

No icon variant

Icon is optional — title and description span the full width.

With icon

Icon shifts content to column 2.

Title only

Title only alert

Description only

Description-only alerts work well for brief notices without a heading.

Design Guidelines

Pair with a relevant icon. Icons give users instant context before they read the text.
Keep descriptions concise. One or two sentences — link to docs for deeper explanations.
Use destructive for real errors. Reserve variant="destructive" for failures that need immediate attention.

Don't

Don't nest alerts. Place a single alert per context — stacking them loses hierarchy.
Don't use destructive for warnings. Use default with a warning icon for non-critical cautions.
Don't replace toasts with alerts. Alerts are inline and persistent; use Toaster for transient feedback.

Developer Reference

Accessibility

role="alert" on the root announces content to screen readers on mount.
Icon child (SVG) causes AlertTitle and AlertDescription to receive col-start-2 automatically.
AlertAction is absolute top-2 right-2 — include sr-only label on icon-only actions.
The left border (border-l-4) provides a visual affordance beyond color alone.

Usage

import {
  Alert,
  AlertTitle,
  AlertDescription,
  AlertAction,
} from "@/components/ui/alert"
import { Info, AlertCircle } from "lucide-react"

// Default
<Alert>
  <Info className="size-4" />
  <AlertTitle>Heads up</AlertTitle>
  <AlertDescription>Your free trial expires in 3 days.</AlertDescription>
</Alert>

// Destructive
<Alert variant="destructive">
  <AlertCircle className="size-4" />
  <AlertTitle>Error</AlertTitle>
  <AlertDescription>Failed to save changes. Please try again.</AlertDescription>
</Alert>

// With dismiss action
<Alert>
  <Info className="size-4" />
  <AlertTitle>Update available</AlertTitle>
  <AlertDescription>Version 2.0 is ready to install.</AlertDescription>
  <AlertAction>
    <button aria-label="Dismiss"><X /></button>
  </AlertAction>
</Alert>