Alert

When to UseCopy Anchor Link

• for a status that lasts as long as its cause, for example “INV-2026-012 is overdue”
• when one click can fix the cause, with an action like “Retry” next to “The payment failed”

When Not to UseCopy Anchor Link

• for the result of an action, like “Invoice sent” (use a toast from Sonner)
• for a decision that users have to make before anything else (use an Alert Dialog)
• for an error in one field of a form (use the FieldError of a Field)
• for the status of one record in a list (use a Badge)

AnatomyCopy Anchor Link

* An Alert has a title, a description, or both.

The icon is any svg that is a direct child of Alert.

VariantsCopy Anchor Link

The variant changes only the color of the icon. Alert doesn’t render an icon, so you pass one. The preview uses InfoIcon, CheckCircleIcon, WarningIcon, and XCircleIcon, which are the icons that a toast shows for the same statuses.

Add an icon and a title that states the status in words to every Alert, as the variants look the same when there is no icon.

BehaviorCopy Anchor Link

An Alert is as wide as its container. It has no close button and isn’t dismissed automatically, so render it for as long as its condition is true.

ContentCopy Anchor Link

AccessibilityCopy Anchor Link

Alert renders a div with role="alert", which is a live region that is assertive and atomic. AlertTitle is a div, not a heading. An Alert can’t receive focus and has no keys; users reach the Button in its action with Tab.

Most screen readers announce an Alert immediately when it is added after the page has loaded. If an Alert is already in the page when it loads, it isn’t announced, according to the ARIA Authoring Practices Guide. If the message can wait its turn, pass role="status", which is polite.

Set aria-hidden on the icon. See Iconography for the rule.

InstallationCopy Anchor Link

npx shadcn@latest add @summit/alert

UsageCopy Anchor Link

import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
import { InfoIcon } from '@phosphor-icons/react';

<Alert>
    <InfoIcon aria-hidden />
    <AlertTitle>Your trial ends in 5 days</AlertTitle>
    <AlertDescription>Add a payment method to keep sending invoices.</AlertDescription>
</Alert>;

Show a StatusCopy Anchor Link

To show a status, set variant and pass the icon for that status.

import { WarningIcon } from '@phosphor-icons/react';

<Alert variant="warning">
    <WarningIcon aria-hidden />
    <AlertTitle>INV-2026-012 is overdue</AlertTitle>
    <AlertDescription>It was due 12 days ago.</AlertDescription>
</Alert>;

Add an ActionCopy Anchor Link

To add an action, write AlertAction last and place an xs Button in it.

import { Alert, AlertAction, AlertDescription, AlertTitle } from '@/components/ui/alert';
import { Button } from '@/components/ui/button';
import { XCircleIcon } from '@phosphor-icons/react';

<Alert variant="destructive">
    <XCircleIcon aria-hidden />
    <AlertTitle>The payment failed</AlertTitle>
    <AlertDescription>The card was declined. Ask the client for another payment method.</AlertDescription>
    <AlertAction>
        <Button variant="outline" size="xs">
            Retry
        </Button>
    </AlertAction>
</Alert>;

Change the RoleCopy Anchor Link

By default, the role is alert. If the message can wait its turn, pass another role.

import { CheckCircleIcon } from '@phosphor-icons/react';

<Alert role="status" variant="success">
    <CheckCircleIcon aria-hidden />
    <AlertTitle>Payment received</AlertTitle>
</Alert>;

API ReferenceCopy Anchor Link

The parts accept the props of a div.

AlertCopy Anchor Link