Shadcn Alert Components

Shadcn Alert Component

The Shadcn Alert is a static callout that draws attention to a message inside the page: a saved change, a failed payment, a quota warning or a list of validation errors. Unlike a toast it does not disappear on its own, and unlike a dialog it does not block the rest of the interface, so it is the right tool for messages that belong next to the content they describe.

From a one line notice to destructive errors, green success messages, amber usage warnings, password rules in a bulleted list and inline Undo or accept and decline buttons, this shadcn alert collection covers the feedback most screens need. The alert is plain HTML built with shadcn/ui, React and Tailwind CSS, with no primitive dependency, so every variant behaves the same next to Radix UI or Base UI components. Dark mode and shadcn CLI installs are included.

What is the Shadcn Alert Component?

An alert is a bordered box with an optional icon, a title and a description. The shadcn/ui version renders a div with role="alert", lays the icon and text out on a small CSS grid, and offers two built-in styles: default and destructive. Success, warning and info styles are just Tailwind classes on top of the default variant, which is how the colored variants on this page are built.

Use an alert when the message should stay visible until the user or the page state changes it. For short, temporary feedback after an action, a Sonner Toast is a better fit. When the user must confirm or cancel before continuing, use an Alert Dialog, and for a small status label inside a row or card, use a Badge.

Anatomy of the Shadcn Alert

15 Shadcn Alert Variants

Each alert variant listed here is previewed live at the top of this page, together with its source code and install command.

• Basic and with icon: A plain description only alert, and the same message with a leading alert circle icon for quick scanning.
• Icon, title and description: The full layout with a check icon, a title and a supporting sentence, the most common alert pattern.
• Destructive: Error alerts using the destructive variant, with the whole message in red or with a neutral title and only the icon colored.
• Success and warning: Green and amber alerts for completed payments and usage limits, either fully tinted or with only the icon tinted.
• With a list: Password requirement alerts that render a bulleted list in the description: fully destructive, neutral with only a red icon, or with the rules already met marked in green.
• With action buttons: Inline alerts with an Undo button, accept and decline icon buttons, or a single close button aligned to the right.

How to Install the Shadcn Alert Component

Set up shadcn/ui in your project if you have not already, then add the Shadcn UI Kit registry to your components.json once:

{
  "registries": {
    "@shadcnuikit": "https://shadcnuikit.com/r/{name}.json"
  }
}

Then install a alert variant by its name:

npx shadcn@latest add @shadcnuikit/alert1

The same command works with pnpm dlx, yarn dlx and bunx --bun. Each variant has a copy button for every package manager, and the code is added to your project as plain React and Tailwind CSS that you can edit freely.

How to Use the Shadcn Alert Component

Import the parts from your components/ui folder, place an icon as a direct child and add a title, a description or both. Pass variant="destructive" for errors.

import { AlertCircleIcon } from "lucide-react"

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

export function PaymentError() {
  return (
    <Alert variant="destructive">
      <AlertCircleIcon />
      <AlertTitle>Unable to process your payment</AlertTitle>
      <AlertDescription>
        Check your card details or try another payment method.
      </AlertDescription>
      <AlertAction>
        <Button variant="outline" size="sm">
          Retry
        </Button>
      </AlertAction>
    </Alert>
  )
}

Why Use the Shadcn Alert Component

• Persistent and in context: The message stays next to the content it refers to, instead of flashing in a corner and disappearing.
• No extra dependencies: It is a styled div with a few slots, so it adds no JavaScript and works with Radix UI or Base UI projects alike.
• Automatic icon layout: Drop an icon in as a direct child and the grid aligns it with the title and description, no wrapper markup needed.
• Theme aware colors: The default and destructive styles use your card and destructive tokens, so they follow your palette and dark mode.
• Easy to extend: Every part accepts className, so success, warning and info styles are a few Tailwind classes away.

Common Alert Use Cases

• Form validation: Summarize errors above a form, such as password rules that are not met yet.
• Payment and billing: Show failed charges, successful payments or an expiring card on billing pages.
• Usage limits: Warn users before they run out of storage, API calls or seats in their plan.
• Confirmation with undo: Confirm a bulk action like moving files and offer an Undo button right inside the alert.
• System notices: Announce scheduled maintenance, a new feature or a degraded service at the top of a dashboard.
• Empty and error states: Explain why a section could not load and what the user can do about it.

Customizing the Shadcn Alert

The two built-in variants live in a cva definition inside alert.tsx, so you can add your own, such as success or warning, next to them. For one-off styles, pass classes to className: tint the whole alert, only the icon, or change the radius and padding. Colors come from the CSS variables in your theme, and you can build a matching palette with the free Theme Generator.

For example, this adds a success variant to the existing definition:

const alertVariants = cva("...", {
  variants: {
    variant: {
      default: "bg-card text-card-foreground",
      destructive: "bg-card text-destructive ...",
      success:
        "bg-card text-green-600 *:data-[slot=alert-description]:text-green-600/90",
    },
  },
})

Alert Accessibility

The root renders with role="alert", which makes it an assertive live region: when an alert is inserted into the page, screen readers announce it right away. That is ideal for errors that appear after submitting a form. For a static notice that is part of the page from the first render, pass role="status" or remove the role so it does not interrupt the user.

Do not rely on color alone to convey meaning. Pair the color with an icon and a clear title such as "Payment failed", and give icon-only action buttons an aria-label. The alert itself has no keyboard interaction; any buttons or links inside it are reached with the normal tab order.

Alert Best Practices

• Lead with the outcome in the title and put the explanation or next step in the description.
• Reserve variant="destructive" for real errors so it keeps its weight when it appears.
• Place the alert close to the content it describes, for example directly above the form it validates.
• Show one alert per problem area; stacking many alerts turns them into noise.
• Offer an action when there is an obvious fix, such as Retry, Undo or Upgrade plan.
• For feedback that should disappear on its own, use a Sonner Toast instead.

Components Related to Alert

Shadcn Alert FAQ

Looking for something else? Browse all shadcn/ui components or ready-made UI blocks built with them.