Alert React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Usage

Import Alert from @/components/ui/alert.

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

export function PaymentError({ onRetry }: { onRetry: () => void }) {
  return (
    <Alert
      tone="danger"
      title="We could not process the payment"
      description="Your bank declined the card. Try another card or pay on delivery."
      actions={
        <>
          <AlertAction onClick={onRetry}>Try again</AlertAction>
          <AlertAction variant="ghost">Pay on delivery</AlertAction>
        </>
      }
      dismissible
      closeLabel="Close"
    />
  )
}

// the parts, for lists and custom layouts
export function ListingChecklist() {
  return (
    <Alert tone="warning">
      <AlertTitle>The listing cannot be published yet</AlertTitle>
      <AlertDescription>
        <ul className="list-disc ps-4">
          <li>Add at least 3 photos</li>
          <li>Fill in the floor area</li>
        </ul>
      </AlertDescription>
      <AlertActions>
        <AlertAction>Complete it</AlertAction>
      </AlertActions>
    </Alert>
  )
}

Props

• titledefault ""
  ReactNode

  The headline, in the tone's text color. Without it the description lines up with the icon.

• descriptiondefault ""
  ReactNode

  The message under the title. Long words wrap instead of overflowing, and links inside stay underlined.

• closeLabeldefault "Dismiss"
  string

  Accessible name of the close button, read by screen readers. Translate it with the rest of the page.

• variantdefault "soft"
  "soft" | "outline" | "solid"

  soft is a tinted surface for most messages, outline a hairline on the page for quieter ones, solid a full fill for urgent banners.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  danger for errors, warning for things that need attention, success for done, info for tips. Also picks the default icon and the screen reader role.

• colordefault ""
  string

  Any CSS color. Replaces the tone for the tint, the border, the fill, the icon and the actions; text on a solid fill turns black or white by lightness.

• sizedefault "md"
  "sm" | "md"

  md for page and section messages (16px padding, 20px icon). sm for inline form messages (12px padding, 13px text, 16px icon).

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corner shape: 0, 12, 16 or 24px; full falls back to 24px. A banner is always square.

• bannerdefault false
  boolean

  A full-bleed page banner: no radius, a bottom border, the content centered in max-w-5xl. It lays out by its own width: one line with the actions at the end from 672px, stacked below that. At the very top of a phone screen, add pt-[env(safe-area-inset-top)].

• dismissibledefault false
  boolean

  Shows a close button. Pressing it sets open to false and the alert collapses out.

• defaultOpendefault true
  boolean

  Starts visible. A server-rendered alert shows up at once and one mounted later fades in; keep it mounted and flip open to collapse it out and expand it back.

• open
  boolean

  Controlled visibility. When set, the parent decides whether a dismiss really closes it.

• onOpenChange
  (open: boolean) => void

  Called with false when the close button is pressed, controlled or not.

• icon
  ReactNode

  The leading icon. Defaults per tone: Info for neutral and info, Sparkles for brand, CircleCheck for success, TriangleAlert for warning, CircleAlert for danger. Pass null to hide it; the text then starts at the edge.

• actions
  ReactNode

  Buttons under the text, usually AlertAction: a small Button (ButtonProps) in the alert's tone and color, solid by default (pass variant for secondary actions) and inverted on a solid alert so it always reads. On a phone two or more share the alert's full width like a native button bar; in a wide banner they sit at the end of the line.

• children
  ReactNode

  Extra content under the description, or the parts (AlertTitle, AlertDescription, AlertActions) for full control over lists, links and custom layouts.

• roledefault ""
  "alert" | "status" | "none"

  The live region. Unset (the empty option), it follows the tone: "alert" for danger and warning (announced at once), "status" for the rest (announced politely). "none" adds no role, for alerts that are part of the page from the start.

• classNames
  Partial<Record<"wrapper" | "container" | "icon" | "content" | "title" | "description" | "actions" | "close", string>>

  Extra classes for the inner parts. wrapper is the full-width collapsing element around the alert (put grid or flex placement there); container is the centered row of a banner.

• className
  string

  Extra classes for the alert surface, merged last. Override the tone vars here, e.g. [--tone-soft:...]. In a flex column or grid the collapse also takes the parent's gap along, so nothing snaps when it closes.

Parts

FAQ

Used in

More React feedback components