# Alert

> An inline message with a status color and icon — info, success, warning, or critical; inline, filled or as a full-width banner.

URL: https://apogee.avaui.dev/docs/alert
Last updated: 2026-10-15

An inline message with a status color and icon — info, success, warning, or critical; inline, filled or as a full-width banner.

Last updated October 15, 2026

```astro
<Alert color="primary" title="Heads up">
A new version of this page is available.
</Alert>
```

## Add

```sh
npx @ava-ui/apogee add alert
```

Uses `@lucide/astro` (`Info`, `CircleCheck`, `TriangleAlert`, `CircleAlert`) for the per-variant icon.

## Usage

```astro
---
import Alert from '@/components/apogee/Alert/Alert.astro'
---
<Alert color="positive" title="Saved">Your changes were saved.</Alert>
```

## API

`@composable` — exposed to Content Editors in AVA. Any other attribute (e.g. `role`, `aria-live`, `id`) passes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `'primary' \| 'neutral' \| 'critical' \| 'positive' \| 'warning'` | `'neutral'` | The hue. |
| `variant` | `'faded' \| 'solid' \| 'banner'` | `'faded'` | Tinted (default), filled, or a full-width strip with a bottom rule and the content in a centred column. |
| `featured` | `boolean` | `false` | Puts the icon in a FeaturedIcon tile. |
| `title` | `string` | — | Optional bold heading above the message. |
| `inline` | `boolean` | `false` | Hides the icon column. |
| `role` | `string` | `'alert'` for critical and warning | Live-region role. Critical and warning alerts announce themselves; pass `role` (or `role="status"`) to override. |
| `class` | `string` | — | Extra classes, appended last. |

Slots: default for the message, `actions` for buttons under it.

## Colors × variants

Every `color`, each with its fixed icon, tinted and filled:

```astro
<Alert color="neutral" title="Note">A neutral callout.</Alert>
<Alert color="primary" title="Info">Informational message.</Alert>
<Alert color="positive" title="Success">Action completed.</Alert>
<Alert color="warning" title="Warning">Check this before continuing.</Alert>
<Alert color="critical" title="Error">Something went wrong.</Alert>
<Alert variant="solid" color="neutral" title="Note">A neutral callout.</Alert>
<Alert variant="solid" color="primary" title="Info">Informational message.</Alert>
<Alert variant="solid" color="positive" title="Success">Action completed.</Alert>
<Alert variant="solid" color="warning" title="Warning">Check this before continuing.</Alert>
<Alert variant="solid" color="critical" title="Error">Something went wrong.</Alert>
```

## Banner and featured icon

A banner spans its container with a rule at the bottom; its content sits in a centred column, the icon hides on phones and the actions move to the end from `md`. Pin it to the bottom on phones with `class="max-md:sticky max-md:bottom-0"`.

```astro
<Alert variant="banner" color="primary" title="New version available">
Reload to get the latest fixes.
<Button slot="actions" size="small">Reload</Button>
</Alert>
<Alert featured color="positive" title="Payment received">Your invoice is paid.</Alert>
```

Dismissal is a Dismissible around the alert: `<Dismissible align="top"><Alert class="pe-10">…</Alert></Dismissible>`.

## Icon slot and roles

A custom icon replaces the colour’s default; critical and warning get `role="alert"` automatically.

```astro
<Alert color="primary" title="New release"><Rocket slot="icon" />Version 0.4 is out.</Alert>
<Alert color="critical" title="Payment failed">Announced as an alert.</Alert>
<Alert color="primary" title="Note">No role: a static callout.</Alert>
```

## States

Alert is static — no hover/focus/disabled states. The one behavioral distinction is static (page) vs dynamic (result of an action), which changes the ARIA role you pass in, not the markup:

```astro
<Alert color="warning" title="Limited availability">
Only 2 left in stock.
</Alert>
<Alert color="critical" title="Couldn't save" role="alert">
Check the highlighted fields and try again.
</Alert>
```

## Examples

Without a title — the message alone takes the primary text color:

```astro
<Alert color="primary">No title, just a message.</Alert>
```

With a link in the body:

```astro
<Alert color="warning" title="Update required">
  Your plan expires soon. <a href="/billing" class="underline">Renew now</a>.
</Alert>
```

## Accessibility

-   Icons are `aria-hidden` — the status is conveyed by the adjacent text, not color/icon alone.
-   Critical and warning alerts get `role="alert"` by default, so they are announced when inserted. Other colours have no role: a static callout needs none. Pass `role` (`"status"`, or `""` for none) to override.

## Tokens

| Token | Used for |
| --- | --- |
| `--background-{hue}-faded` / `--border-{hue}-faded` | Surface and border of the `faded` variant, per `color` |
| `--foreground-{hue}` | Icon of the `faded` variant |
| `--background-{hue}` / `--on-{hue}` | Surface and text of the `solid` variant |
| `--foreground-neutral` | Title text |
| `--foreground-neutral-faded` | Body text (when a title is present) |

## Do / Don’t

-   **Do** match the variant to the message’s actual severity — don’t use `critical` for a neutral notice.
-   **Do** keep the title short; put detail in the body.
-   **Don’t** stack more than one Alert for the same event — pick the highest-severity one.
-   **Don’t** use `critical` for destructive-action confirmation — that’s a dialog’s job, not an inline alert’s.

## Content

-   Title: 2–5 words, sentence case, no ending period, states the outcome (“Couldn’t save”, not “Error”).
-   Body: one or two short sentences. Say what happened and, for warnings and critical alerts, what to do next.

## Related

[

ToastA transient notification, fired imperatively from anywhere on the page.

](https://apogee.avaui.dev/docs/toast)[

DismissibleWrap anything with a close button, with an optional auto-dismiss timeout.

](https://apogee.avaui.dev/docs/dismissible)[

EmptyStateA centered placeholder for empty views — no results, first run, a cleared list.

](https://apogee.avaui.dev/docs/empty-state)