Alert

Anatomy#

Installation#

$ pnpm dlx shadcn@latest add https://www.prfct.dev/r/alert.json

Usage#

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

<Alert variant="warning">
  <TriangleAlertIcon />
  <AlertTitle>Your trial ends in 3 days</AlertTitle>
  <AlertDescription>Add a payment method to keep your projects running.</AlertDescription>
</Alert>

Examples#

Variants#

Five variants map to the status scales. Each one tints its background with step 2, draws its border with step 6 and sets its text with steps 11 and 12 — so every variant meets 4.5:1 in both modes without extra work.

With an action#

Place one follow-up action in AlertAction. It sits on the right, vertically centered, and the alert reserves space so text never runs underneath it. Keep it to a single small button — an alert with a toolbar is a card.

With a link#

Links inside AlertDescription are underlined and inherit the variant's text color, so they stay legible on every tint.

With a list#

When several things need fixing, list them. People scan lists; they skim paragraphs.

Title only#

A short message doesn't need a description. The icon is optional — drop it for neutral notes that shouldn't draw the eye.

Guidelines#

When to use#

• To explain a condition that affects the whole page or section: an outage, a limit, a pending verification.
• To summarize a set of form errors above the form, in addition to inline errors on each field.
• To surface information that must stay visible until the situation changes.

When not to use#

• For confirmation of something the person just did — use a Toast. It appears where attention already is and disappears on its own.
• For errors on a single field — use FieldError inside a Field, next to the input.
• For decisions that block progress — use an Alert Dialog.
• For marketing content. An alert borrows the urgency of status colors; spending it on promotions teaches people to ignore it.

Choose the lowest variant that is true#

Status colors are a finite budget. If nothing is wrong, the alert is default or info, even when the message feels important. Reserve warning for things that will break, and destructive for things that are broken.

Writing#

• Lead with the consequence, not the cause: Builds will queue once you reach the limit, not Build minute usage is at 90%.
• Say what to do next. Every warning and error should name an action or link to one.
• Keep titles to one line and descriptions to two sentences. Longer content belongs on its own page.
• Don't stack alerts. Two or more alerts in one place compete; combine them or show the most severe.

Accessibility#

Alerts are live regions, so their content is announced when it appears without moving focus.

• Politeness follows severity. destructive and warning render role="alert" and are announced immediately, interrupting whatever the screen reader was saying. All other variants render role="status" and wait for a pause. Pass role to override, for example role="note" for static content that should not be announced at all.
• Insert, don't reveal. Live regions announce changes. An alert that is present on page load is read in document order; one added later — after a failed submission, say — is announced as it appears.
• Color is never the only signal. Pair every status variant with an icon and a title that states the status in words.
• Actions stay in the tab order. Buttons and links inside an alert are reachable with Tab and never steal focus when the alert appears.

API reference#

Alert#

The container. Renders a <div> with data-slot="alert" and a data-variant attribute.

AlertTitle#

A single line that states the message. Renders a <div>; when the alert has an icon, it starts in the second column.

AlertDescription#

Supporting text, links and lists. Colored with step 11 of the variant's scale.

AlertAction#

A slot for one follow-up action, pinned to the right edge. The alert adds right padding when an action is present.