# Alert

An inline banner in 5 colors and 2 sizes, with an optional close button and action.

- Category: Core Elements
- Page: https://wunderui.com/components/alert
- Tier: Free

## Install

```bash
npx wunderui-cli add alert
```

## Import

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

## Minimal usage

Then use it:

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

export function SavedNotice() {
  return (
    <Alert variant="positive">
      <AlertTitle>Settings saved</AlertTitle>
      <AlertDescription>Your notification preferences have been updated.</AlertDescription>
    </Alert>
  )
}
```

Expected result: You should see a green banner with a check icon, a bold title and one line of text under it.

## Usage

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

export function Example() {
  return (
    <Alert variant="positive">
      <AlertTitle>Settings saved</AlertTitle>
      <AlertDescription>Your notification preferences have been updated.</AlertDescription>
    </Alert>
  )
}
```

## When to use

### Use Alert for

- A message that belongs to the page or to one section and stays until the cause is fixed or the reader closes it
- The result of a form or a bulk action, shown where people are looking
- A notice at the top of a page, such as an ending trial or a planned maintenance window

### Use something else

- [Toast](https://wunderui.com/components/toast) for a short confirmation that appears after an action and disappears by itself
- [Alert Dialog](https://wunderui.com/components/alert-dialog) for a decision people must make before they can go on
- [Empty State](https://wunderui.com/components/empty-state) for a list or a page that has nothing in it yet

## Keyboard

The alert itself is not focusable. Only the action and the close button are in the tab order.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the action and to the close button. |
| `Enter` or `Space` | Presses the focused button: runs the action, or calls `onClose`. |

## Behavior

What the alert announces, how it is coloured and what it leaves to you.

- **Announcement:** The alert is an assertive live region: a screen reader reads it as soon as it is added, and does not read one that was there at load. For a non-urgent message, use the polite status role.
- **Colour:** A coloured alert has a tint fill with text, icon and border in the tint text colour of the same hue; plain uses the card colour. Every pair is a fixed token, so it works in light and dark.
- **Size:** Large stacks title, text and action in a column. Small keeps them in one row, which fits above a table or at the top of a page; the text truncates there, so long messages belong in large.
- **Closing:** Pressing the close button calls your handler; the alert does not remove itself. Stop rendering it yourself, and move focus somewhere sensible if the alert held it.
- **Width:** The alert is a block that fills its container. Set the width on the container, not on the alert.
- **Motion:** The alert has no entrance or exit animation. The close button sits at 70 % opacity and fades to 100 % on hover and focus.
- **Reduced motion:** With reduced motion on nothing changes: the only motion is an opacity fade, which stays.

## Anatomy

- `Alert`: The banner, with role alert. It comes in five variants (plain, positive, primary, negative, warning) and two sizes (large, small), and picks its icon from the variant. With size inline it is a static line of text without a box and without the role.
- `Icon`: The leading icon: a check circle, or a warning triangle for negative and warning. You can replace it or hide it.
- `AlertTitle`: The bold first line. In the small size it stays on one line and truncates only when the banner is very narrow.
- `AlertDescription`: The message. In large it wraps under the title; in small it takes the rest of the line and ends in an ellipsis.
- `Close button`: A native button named Dismiss, drawn only when a close handler is set.
- `Action`: Any Button after the description, usually plain and small. In large it sits under the text; in small it ends the row.
- `InlineNote`

## Best practices

### Do

- Say what happened in the title and what to do next in the text, like Changes couldn't be saved and Check your connection and try again.
- Pick the colour for the meaning: positive for done, negative for failed, warning for attention, primary for information and plain for a neutral note.
- Place the alert next to what it is about: under the field that failed, or at the top of the section it describes.
- Give an alert that is only information a close button, and keep one that blocks people on the page until the cause is fixed.

### Don't

- Don't use an alert for a confirmation that should vanish by itself. A Toast fits a short message after an action.
- Don't stack more than two or three alerts. Merge them into one, or move the details into a list.
- Don't rely on the colour alone. The title and the text must say what happened, because not everyone sees the colour.
- Don't put long text or a form in an alert. Link to a page for the details.

## API reference

### Alert

| Prop | Type | Default | Description |
|---|---|---|---|
| icon | React.ReactNode |  | Replaces the leading icon. Without it the alert shows a check circle, or a warning triangle for `negative` and `warning`; with `size="inline"` a shield check, or the triangle for `warning`. `null` hides it. |
| onClose | () => void |  | Called when the close button is pressed. The close button is only drawn when this is set. |
| size | "small" \| "inline" \| "large" | "large" | `large` stacks the title, the text and an action in a column; `small` keeps them in one row; `inline` drops the box for a 12 px line of text with a 14 px icon and no `role="alert"`. `large` by default. |
| variant | "warning" \| "plain" \| "primary" \| "positive" \| "negative" | "plain" | The colour and meaning: `plain` for a neutral note, `positive` for success, `primary` for information, `negative` for an error and `warning` for attention. `plain` by default. |

Also accepts React.HTMLAttributes attributes.

### AlertDescription

| Prop | Type | Default |
|---|---|---|


Also accepts React.HTMLAttributes attributes.

### AlertTitle

| Prop | Type | Default |
|---|---|---|


Also accepts React.HTMLAttributes attributes.

### InlineNote

| Prop | Type | Default |
|---|---|---|
| children* | React.ReactNode |  |
| className | string |  |
| icon | React.ReactNode |  |
| tone | "neutral" \| "warning" | "neutral" |

## Examples

### Content: text, an action or a close button

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

export function Example() {
  return (
    <Alert variant="primary">
      <AlertTitle>Update available</AlertTitle>
      <AlertDescription>A new version is ready to install.</AlertDescription>
    </Alert>
  )
}
```

### Icon: the default, a custom one or none

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

export function Example() {
  return (
    <Alert variant="positive">
      <AlertTitle>Settings saved</AlertTitle>
      <AlertDescription>Your notification preferences have been updated.</AlertDescription>
    </Alert>
  )
}
```

### Inline: a line of supporting text, plain or warning

```tsx
import { Alert } from "@/components/ui/alert"

export function Example() {
  return (
    <Alert size="inline">
      Only people with the link can join this workspace.
    </Alert>
  )
}
```

## In context

### Save error with a retry

The alert sits under the field it is about and offers the one thing people can do. When it works, the same place shows the result.

```tsx
import { useState } from "react"
import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"

export function ProfileForm() {
  const [saved, setSaved] = useState(false)

  return (
    <div className="flex flex-col gap-3">
      <Input aria-label="Display name" defaultValue="Nora Lindgren" />
      {saved ? (
        <Alert variant="positive">
          <AlertTitle>Profile saved</AlertTitle>
          <AlertDescription>Your changes are live.</AlertDescription>
        </Alert>
      ) : (
        <Alert variant="negative">
          <AlertTitle>Changes couldn't be saved</AlertTitle>
          <AlertDescription>Check your connection and try again.</AlertDescription>
          <Button variant="plain" size="sm" onClick={() => setSaved(true)}>
            Try again
          </Button>
        </Alert>
      )}
    </div>
  )
}
```

### Trial banner at the top of a page

The small size is one line: title, text and a button in a row. People can close it and the page content moves up.

```tsx
import { useState } from "react"
import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"
import { Button } from "@/components/ui/button"

export function TrialBanner() {
  const [open, setOpen] = useState(true)

  return (
    <div className="flex flex-col gap-3">
      {open && (
        <Alert variant="warning" size="small" onClose={() => setOpen(false)}>
          <AlertTitle>Trial ends soon</AlertTitle>
          <AlertDescription>3 days left.</AlertDescription>
          <Button variant="plain" size="sm">
            Choose a plan
          </Button>
        </Alert>
      )}
      <h1 className="text-lg font-semibold text-foreground">Overview</h1>
    </div>
  )
}
```

### Result of an import

Two alerts after a bulk action: what worked and what was skipped, with a button for the details.

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

export function ImportResult() {
  return (
    <div className="flex flex-col gap-2">
      <Alert variant="positive">
        <AlertTitle>12 contacts imported</AlertTitle>
        <AlertDescription>They were added to the list Customers.</AlertDescription>
      </Alert>
      <Alert variant="warning">
        <AlertTitle>3 rows skipped</AlertTitle>
        <AlertDescription>These rows have no email address.</AlertDescription>
        <Button variant="plain" size="sm">
          Download report
        </Button>
      </Alert>
    </div>
  )
}
```

## For AI agents

`get_component("alert")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
