# Alert

> A React alert for inline messages about a page or section, from a failed payment to a maintenance banner, in three variants and six tones.

- Type: React component (Feedback)
- Access: Free (the source is open to everyone)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add alert`
- Docs: https://wingo-ui.com/components/alert

## Interaction

The alert sits in the page and never blocks it: server-rendered alerts show up as they are, and one that appears later (after a failed submit) fades in without pushing the page around. Its actions are real buttons that match the tone, and on a solid fill they flip to the fill's text color. With dismissible on, the close button (or Tab to it, then Enter or Space) fades the alert out while its space collapses and the content below slides up; open it again and it springs back in. With reduced motion it only fades. Closing it with focus inside moves focus to the next control instead of dropping it on the page (after a tap a text field is skipped, so the phone keyboard never pops up). Errors and warnings are announced by screen readers right away, other tones politely. On a phone two or more actions stretch into a full-width button bar under the text, and the close button keeps a 44px hit area. As a banner it spans the page: one line with the actions at the end once it is wide enough, stacked on a phone or in a narrow panel.

## Installation

```bash
npx wingo-ui@latest add alert
```

The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add https://wingo-ui.com/r/alert.json`

Files:

- `components/ui/alert.tsx`

npm dependencies: `npm i motion lucide-react`

Wingo UI dependencies (installed automatically):

- [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md))
- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [Tones](https://wingo-ui.com/components/tones) ([Markdown](https://wingo-ui.com/components/tones.md))
- [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title?` | `ReactNode` | `""` | The headline, in the tone's text color. Without it the description lines up with the icon. |
| `description?` | `ReactNode` | `""` | The message under the title. Long words wrap instead of overflowing, and links inside stay underlined. |
| `closeLabel?` | `string` | `"Dismiss"` | Accessible name of the close button, read by screen readers. Translate it with the rest of the page. |
| `variant?` | `"soft" \| "outline" \| "solid"` | `"soft"` | soft is a tinted surface for most messages, outline a hairline on the page for quieter ones, solid a full fill for urgent banners. |
| `tone?` | `"neutral" \| "brand" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | 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. |
| `color?` | `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. |
| `size?` | `"sm" \| "md"` | `"md"` | md for page and section messages (16px padding, 20px icon). sm for inline form messages (12px padding, 13px text, 16px icon). |
| `radius?` | `"none" \| "sm" \| "md" \| "lg" \| "full"` | `"md"` | Corner shape: 0, 12, 16 or 24px; full falls back to 24px. A banner is always square. |
| `banner?` | `boolean` | `false` | 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)]. |
| `dismissible?` | `boolean` | `false` | Shows a close button. Pressing it sets open to false and the alert collapses out. |
| `defaultOpen?` | `boolean` | `true` | 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. |
| `role?` | `"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

### AlertTitle (component)

The headline as a child of Alert, sized by the alert's size and colored by its tone. Use it instead of the title prop when the headline needs markup. Takes any div prop.

### AlertDescription (component)

The message under the title. Takes paragraphs, lists and links; links stay underlined so they read as links on touch screens too. Takes any div prop.

### AlertActions (component)

The row of actions under the text. Wraps on phones, where two or more actions stretch into a full-width button bar, and moves to the end of the line in a wide banner.

### AlertAction (component)

A small Button that matches its alert: the alert's tone and color by default, solid unless you pass a variant, and inverted on a solid alert so it always reads. Takes every Button prop (loading, leftIcon, onClick, asChild).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `"solid" \| "soft" \| "outline" \| "ghost" \| "link"` | `"solid"` | Button variant; use ghost or outline for secondary actions. |
| `size?` | `ButtonSize` | `"sm"` | Button size; sm fits the alert's padding. |
| `tone?` | `Tone` |  | Overrides the alert's tone for this action. |

### AlertProps (type)

Props of Alert, for wrappers that forward them.

### AlertTone (type)

The tone union: neutral, brand, success, warning, danger, info.

## Examples

- **Tones**: Six tones in the soft variant, each with its own icon. Danger and warning are announced right away.
- **Variants**: soft, outline and solid. AlertAction follows the tone, and flips to the fill's text color on solid.
- **Dismissible**: The close button collapses the alert and the card below slides up. Bring it back to see it expand in.
- **Inline form message**: size sm under a field, opened and closed by the validation. aria-describedby links it to the input.
- **Page banner**: banner spans the page. It lays out by its own width: one line when wide, stacked here and on a phone.
- **Custom color and icon**: Any CSS color replaces the tone; text on a solid fill turns black or white by itself.
- **Parts**: AlertTitle, AlertDescription and AlertActions for lists, links and custom layouts.
- **Without a title or icon**: The description lines up with the icon, and with icon={null} the text starts at the edge.

## See also

- [Alert Dialog](https://wingo-ui.com/components/alert-dialog) ([Markdown](https://wingo-ui.com/components/alert-dialog.md))
- [Badge](https://wingo-ui.com/components/badge) ([Markdown](https://wingo-ui.com/components/badge.md))
- [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md))
- [Tones](https://wingo-ui.com/components/tones) ([Markdown](https://wingo-ui.com/components/tones.md))
- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))

---

Canonical: https://wingo-ui.com/components/alert
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt