# Alert

Shows a persistent message inside the page, announced by urgency.

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

<Alert>
  <AlertTitle>Sync complete</AlertTitle>
  <AlertDescription>1,240 orders imported from the ERP at 9:42 AM.</AlertDescription>
</Alert>
```

## Usage

### What you provide
- `variant`: `default` | `destructive`.
- A 16px Heroicons Micro icon as the first child (the Alert positions it), e.g. `ExclamationCircleIcon` for errors.
- `AlertTitle`: what happened. `AlertDescription`: what to do now.

### Usage
- For short-lived feedback after an action, use a toast, not an Alert.
- Errors state the problem and the fix, without apologizing ("The card has expired. Update your payment method.").

## Accessibility

- PUI announces by urgency: the `destructive` variant uses `role="alert"`; the default variant uses `role="status"`, so it doesn't interrupt reading. Pass `role` to override when needed.
- Reading an alert needs no interaction and the alert never takes focus just to be read. `Tab` reaches only the links and buttons inside it.
- The type is clear without color or icon alone: the title says what happened and the description says what to do.
- Dismissible alerts have a visible close button; after closing, focus moves to a predictable place.
- Errors about a field belong next to that field (`FieldError`), not only in an alert.

_Adapted from Magoo 1.6.0 by Marcelo Sales: [Alerts](https://magoo.cc/en/components/messages/alerts.html) (`alertas`). Magoo is educational guidance; test the behavior in your implementation._

## API

Install:

```bash
npx @aline-aroucha/pui add alert
```

```tsx
<Alert>
  <Icon />
  <AlertTitle />
  <AlertDescription />
</Alert>
```

### Alert

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "destructive"` | `"default"` | Style and urgency. `destructive` uses role="alert"; `default` uses role="status". |
| `role` | `string` | `by variant` | Overrides the announcement role. |
| `children` | `ReactNode` | — | An optional icon, then AlertTitle and AlertDescription. |

### AlertTitle

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | What happened. |

### AlertDescription

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | What to do now. |

## Related pages

- [Badge](https://aline-aroucha.github.io/pui/components/badge.html)
- [Field](https://aline-aroucha.github.io/pui/components/field.html)
- [Skeleton](https://aline-aroucha.github.io/pui/components/skeleton.html)

---
PUI documentation · https://aline-aroucha.github.io/pui/components/alert.html