Alert

Use an Alert to call attention to information that affects the current page or task: warnings about expiring payment methods, errors that need recovery, success confirmations worth keeping visible, and neutral guidance at the point of action.

Alerts live in the flow of the page, near the content they explain, and stay there until removed. That persistence is the dividing line from Toast: a toast confirms and disappears, while an alert remains as long as its condition does. When information must block all work until a person decides — deleting data, leaving with unsaved changes — use Alert Dialog instead.

An Alert has a container, optional icon, title, description, and optional actions. The title names what happened in a few words. The description explains the consequence or what to do next. Actions sit in their own column on wide screens and drop below the text on narrow ones, so recovery is never more than one glance away.

When you render an icon as the first child, it occupies a fixed column aligned to the first line of text; the title and description shift to the second column automatically.

Choose the variant by meaning, not by color preference:

• default — neutral information with no state attached.
• info — guidance that changes how someone completes the current task.
• success — confirmation that completed work was saved or applied.
• warning — risk ahead: expiring cards, limits approaching, irreversible settings.
• error — something failed and needs recovery before the task can continue.

Each variant pairs a border and background tint with matching icon color. Because the tint uses low-alpha tokens over the card background, variants remain distinguishable in dark mode without vibrating against it.

Keep alerts close to the content they explain: a billing warning belongs on the billing page next to the payment method, not in a global banner where its context is lost. One alert per condition; when several conditions fire at once, consolidate them into a single message listing each item rather than stacking five boxes.

Render an Alert only while its condition holds. A stale success banner left on the page teaches people to ignore every other alert — see Don't do this.

Every Alert renders role="alert", so content inserted into the DOM inside it is announced immediately by screen readers, including failures reported after an async request completes. This urgency cuts both ways: reserve the component for information genuinely worth interrupting for, and note that an alert present at page load is typically not announced — sighted-only emphasis there is fine, but critical load-time context also needs a heading or focus target.

Do not rely on color alone. The variant color is always paired with your title and description text; add an icon when the extra cue helps scanning. Action buttons inside AlertAction are ordinary buttons, reachable by Tab with visible focus rings.

Text wraps within the container rather than truncating, so localized descriptions grow downward without clipping the action column. The grid uses logical properties and mirrors under dir="rtl". Colors come from theme tokens, so all five variants hold WCAG-readable contrast in dark mode automatically.

import {
  Alert,
  AlertDescription,
  AlertAction,
  AlertTitle,
} from "@/components/ui/alert";

<Alert variant="warning">
  <TriangleAlertIcon />
  <AlertTitle>Payment method expires soon</AlertTitle>
  <AlertDescription>
    Update the card on file before June 14 to keep automations running.
  </AlertDescription>
  <AlertAction>
    <Button variant="secondary" size="sm">Update card</Button>
  </AlertAction>
</Alert>

The same file also exports the modal family — AlertDialog, AlertDialogTrigger, AlertDialogPopup, and related parts. Those follow Base UI's Alert Dialog semantics instead; see Alert Dialog for when a blocking decision is appropriate and how it differs from Dialog.

Marketing decoration

// Bad
<Alert variant="error">
  <AlertTitle>🔥 Summer sale ends tonight!</AlertTitle>
  <AlertDescription>Use code SUMMER for 20% off.</AlertDescription>
</Alert>

// Good
<div className="rounded-xl border bg-card p-3.5 text-sm">
  Use code <strong>SUMMER</strong> for 20% off before midnight.
</div>

Every red box trains people a little more to skim past red boxes. When promotions wear error styling, real errors lose the urgency they depend on — and screen-reader users get "alert" announced for an advertisement. Style marketing content neutrally and save the component for conditions that affect the task.

Warnings without a consequence

// Bad
<Alert variant="warning">
  <AlertTitle>Warning!</AlertTitle>
  <AlertDescription>Please review your settings.</AlertDescription>
</Alert>

// Good
<Alert variant="warning">
  <AlertTitle>Deploys paused for this repository</AlertTitle>
  <AlertDescription>
    Billing is suspended. Restore payment within 7 days to keep deploy history.
  </AlertDescription>
</Alert>

"Warning" announces that something might be wrong somewhere, which helps no one deciding what to do next. Name the affected thing in the title and state what changes if nothing happens. If you cannot write the consequence, the alert probably is not needed yet.

One alert per failure

// Bad
<Alert variant="error"><AlertTitle>Name is missing.</AlertTitle></Alert>
<Alert variant="error"><AlertTitle>Email is invalid.</AlertTitle></Alert>
<Alert variant="error"><AlertTitle>Password is too short.</AlertTitle></Alert>

// Good
<Alert variant="error">
  <AlertTitle>Fix 3 fields before saving</AlertTitle>
  <AlertDescription>
    <ul>
      <li>Name is required.</li>
      <li>Email must include an @.</li>
      <li>Password must be at least 12 characters.</li>
    </ul>
  </AlertDescription>
</Alert>

A stack of near-identical boxes shouts the same interruption three times, triples the visual noise, and pushes the form itself off screen. Consolidate into one alert with a list, and keep per-field messages next to their fields where correction happens.

Each example places the alert inside the task that produces it, including the action, result, and recovery path where they matter.

With Icon

Generate a new set of recovery codes and see how the alert explains the consequence before and after the action.

With Icon and Action Buttons

Turn on two-step verification, defer it, or return to the setup from the same account-security workflow.

Info Alert

Give neutral guidance at the point where it changes how someone completes a form.

Success Alert

Confirm a saved profile change while keeping the edited field and next state in view.

Warning Alert

Warn about an expiring payment method and show what changes after it is replaced.

Error Alert

Preserve the failed value, explain the valid format, and let the user recover in place.

Standalone notice

A compact warning with icon and no actions — the smallest complete alert.

The inline family accepts native element props plus:

Alert renders role="alert" unconditionally, which drives the announcement behavior described above. Render it only when its content should be announced or emphasized; use plain containers for decorative callouts.

The modal parts (AlertDialog and children) forward Base UI Alert Dialog props and are documented on the Alert Dialog page.