# Alert

An inline banner with a title, optional body and caller-supplied actions. Use info, success, warning or danger to communicate the kind of message. Static banners are named sections; opt into status or alert for dynamic updates.

## Usage

### When to use

- Show a message that belongs to the current page, such as a saved setting or a failed upload.
- Explain a condition and offer an optional next step beside it.

### When not to use

- A destructive choice that requires confirmation. Use AlertDialog.
- A short message that disappears after an action. Use Toast.
- An empty successful result. Use EmptyState.

## Variants

### variant

The message type. Each value uses its status soft pair: info, success, warning or danger.

Values: `info`, `success`, `warning`, `danger`. Default: `info`.

## Examples

### Inline guidance

```tsx
<Alert title="Your workspace is ready">Invite a teammate to start reviewing projects together.</Alert>
```

### With an action

```tsx
<Alert variant="warning" title="Storage is nearly full" action={<Link href="#storage">Manage storage</Link>}>Remove unused files before your next upload.</Alert>
```

### Dismissible update

The parent removes the banner when onDismiss runs. Supply a specific accessible name for the close button.

```tsx
<Alert variant="success" title="Changes saved" role="status" dismissible dismissLabel="Dismiss saved changes message" onDismiss={dismissAlert}>Your project settings are up to date.</Alert>
```

## Do and don't

### Do

- Write a short title and explain the next step in the body.
- Use caller-supplied actions to resolve a warning or error.
- Provide dismissLabel and remove the banner in onDismiss when dismissal is allowed.

### Don't

- Do not use Alert for confirmation dialogs; use AlertDialog.
- Do not announce every static banner as an alert.
- Do not rely on the icon or color alone to communicate the message.

## Props

| Name | Type | Values | Default | Description |
| --- | --- | --- | --- | --- |
| `variant` | `enum` | `info`, `success`, `warning`, `danger` | `info` | The message type. Each value uses its status soft pair: info, success, warning or danger. |
| `title` (required) | `node` |  |  | Short heading that names the banner. |
| `icon` | `node` |  |  | Decorative icon replacing the variant icon. null hides the icon. |
| `action` | `node` |  |  | An action such as Button or Link, supplied by the caller. |
| `dismissible` | `boolean` |  | `false` | Shows a dismissal button. true requires dismissLabel and onDismiss. |
| `dismissLabel` | `string` |  |  | Accessible name of the dismissal button, required when dismissible is true. |
| `onDismiss` | `function` |  |  | Called when the dismissal button is activated. The parent removes the banner. Required when dismissible is true. |

### Slots

| Name | Required | Description |
| --- | --- | --- |
| `children` | no | Optional message body. |

## Anatomy

| Part | Description |
| --- | --- |
| `root` | Named section with a soft status fill and border, and primary text. |
| `icon` | Decorative 16px variant icon in the status color, in a box one line tall so it stays level with the first line of the title. Replaced by icon or hidden with icon={null}. |
| `content` | Column that holds the title, body and optional actions. |
| `title` | Heading that names the section by default. |
| `body` | Optional body in primary text, like the title. |
| `actions` | Caller-supplied action below the message. |
| `close` | Optional dismissal button, named by dismissLabel. |
| `hitArea` | Transparent minimum target around the dismissal button. |

## Accessibility

Role: `region`

| Keys | Action |
| --- | --- |
| `Tab` | Focus a supplied action or the dismissal button. |
| `Enter / Space` | Activate the focused dismissal button. |

- The title names the section unless aria-label or aria-labelledby supplies a different name.
- Variant alone does not create a live region. Use role="status" for polite updates or role="alert" for urgent updates.
- The icon is decorative; the title and body carry the message.
- Dismissal remains under parent control. Alert never hides itself.

## Install

```bash
npx shadcn add https://werewolf-ui.vercel.app/r/alert.json
```

This also adds `styles/werewolf.css`, the tokens every component uses, and any other component it needs. Import that file once in your root CSS, after `@import "tailwindcss"`, with a path relative to that CSS file (from `app/globals.css` it is `@import "../styles/werewolf.css"`).