---
title: Alert
description: Contextual alert message
visibility: guest
draft: false
---

# Alert

An inline notification banner for surfacing status, warnings, or errors. Alerts support four semantic variants, optional titles, actions, and dismissal.

## Live Sandbox

This is a hydrated playground for the component. Toggle "Live preview" on the block below to swap the static HTML render for a real Livewire instance — every prop in the component's sandbox schema becomes an editable form field inside the iframe, so you can try different prop combinations live without writing any local code.

:::preview{title="Sandbox" sandbox="alert" props='{"variant":"warning","title":"Heads up","body":"Validate every input before submitting."}'}
<x-wirekit::alert variant="warning" title="Heads up">Validate every input before submitting.</x-wirekit::alert>
:::

## Basic Usage

:::preview{title="Simple alert"}
<x-wirekit::alert>
    A new version of WireKit is available.
</x-wirekit::alert>
:::

## Variants

Each variant has a distinct semantic meaning and color. The background is a subtle tint derived via `color-mix()` from the matching token.

:::preview{title="All four variants"}
<x-wirekit::stack gap="sm">
    <x-wirekit::alert variant="info">Heads up — this is informational.</x-wirekit::alert>
    <x-wirekit::alert variant="success">Your changes have been saved.</x-wirekit::alert>
    <x-wirekit::alert variant="warning">Your trial expires in 3 days.</x-wirekit::alert>
    <x-wirekit::alert variant="danger">Failed to connect to the server.</x-wirekit::alert>
</x-wirekit::stack>
:::

## With Title

:::preview{title="Alert with title"}
<x-wirekit::alert variant="warning" title="Unsaved changes">
    You have unsaved changes that will be lost if you leave this page.
</x-wirekit::alert>
:::

## Dismissible

Add `dismissible` to render a close button. Dismissal is handled by a tiny Alpine `x-data` block — no JavaScript bundle additions beyond the existing Alpine.

:::preview{title="Dismissible alert"}
<x-wirekit::alert variant="info" dismissible title="Tip">
    You can personalize this theme in your settings.
</x-wirekit::alert>
:::

## Actions Slot

Attach action buttons below the message via the `actions` slot:

:::preview{title="Alert with actions"}
<x-wirekit::alert variant="danger" title="Connection lost" style="max-width: 28rem;">
    Unable to sync your data.
    <x-slot:actions>
        <x-wirekit::button size="sm" intent="danger">Retry</x-wirekit::button>
        <x-wirekit::button size="sm" intent="neutral" surface="ghost">Dismiss</x-wirekit::button>
    </x-slot:actions>
</x-wirekit::alert>
:::

## Without Icon

Hide the default variant icon with `:icon="false"`. This yields a quieter look — useful inside compact layouts or when the surrounding copy already conveys the severity.

:::preview{title="Alert without icon"}
<x-wirekit::alert variant="info" :icon="false">
    A quieter alert, no icon.
</x-wirekit::alert>
:::

:::preview{title="All four variants without icons"}
<x-wirekit::alert variant="info" :icon="false">Heads up — this is informational.</x-wirekit::alert>
<x-wirekit::alert variant="success" :icon="false">Your changes have been saved.</x-wirekit::alert>
<x-wirekit::alert variant="warning" :icon="false">Your trial expires in 3 days.</x-wirekit::alert>
<x-wirekit::alert variant="danger" :icon="false">Failed to connect to the server.</x-wirekit::alert>
:::

## Width & Layout

Alerts are block-level elements that fill their parent container by default. Control the width with Tailwind utility classes directly on the component — `class` is applied to the root element:

```blade
{{-- Constrain to a max width --}}
<x-wirekit::alert class="max-w-lg" variant="info">Narrow alert.</x-wirekit::alert>

{{-- Fixed width --}}
<x-wirekit::alert class="w-96" variant="success">Fixed 384px wide.</x-wirekit::alert>

{{-- Center a constrained alert --}}
<x-wirekit::alert class="max-w-md mx-auto" variant="warning">Centered alert.</x-wirekit::alert>
```

Height is determined automatically by the content. The alert grows to fit its message, title, and actions.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | string | `'info'` | `primary`, `neutral`, `info`, `success`, `warning`, `danger`. `primary` is a visual synonym of `info` (both tint with `--color-wk-accent`); `neutral` is a quiet gray treatment for non-severity-bearing notices. See [Variants & Intents](../variants-and-intents.md) for the cross-component reference. |
| `intent` | string\|null | `null` | Canonical name for the color axis — the same spelling Button and Badge use: `primary`, `neutral`, `info`, `success`, `warning`, `danger`. Falls back to `variant` when omitted, and wins over it when both are given. |
| `title` | string\|null | `null` | Optional bold title above the body |
| `dismissible` | bool | `false` | Show a close button that hides the alert |
| `icon` | bool | `true` | Whether to render the default variant icon |
| `animateIn` | string\|null | `null` | Entrance-reveal preset (e.g. `'fade'`, `'slide-up'`, `'scale-in'`) — inline alternative to wrapping in `<x-wirekit::reveal>`. See [docs/animations.md](../animations.md) for the full preset list. Respects `prefers-reduced-motion: reduce`. |
| `scope` | string\|null | `null` | Scoped personalization name |

## Slots

| Slot | Description |
| --- | --- |
| Default | Body text content |
| `title` | Bold heading above the body |
| `actions` | Action buttons/links below the body |
| `iconSlot` | Custom icon that overrides the variant-derived default icon |

## Accessibility

- **Role:** `danger` alerts use `role="alert"` (assertive announcement). All other variants use `role="status"` (polite).
- **Screen reader prefix:** Each alert starts with a visually hidden variant label (`"Warning: ..."`, `"Error: ..."`) so the variant is announced even without visual context.
- **Icons are decorative** — marked `aria-hidden="true"` since the meaning is conveyed by the text.
- **Dismiss button** has `aria-label="Dismiss"` and visible focus ring.

## Keyboard Interaction

This component is purely presentational and does not respond to keyboard input.

## Pitfalls

- **Don't use an alert as a permanent UI element.** Alerts are status messages — for persistent banners, use `<x-wirekit::callout>`. The semantic difference matters for screen readers.
- **Don't show ten alerts at once.** WCAG 2.4.3 (Focus Order) suffers when multiple `aria-live="assertive"` regions fire simultaneously. Group related warnings into a single alert with a list, or use `<x-wirekit::toast-region>` for transient notifications.

## Design Tokens

| Token | Purpose |
| --- | --- |
| `--color-wk-accent` | `info` variant icon + border tint |
| `--color-wk-success` | `success` variant icon + border tint |
| `--color-wk-warning` | `warning` variant icon + border tint |
| `--color-wk-danger` | `danger` variant icon + border tint |
| `--color-wk-bg-elevated` | Base background mixed into variant tint |
| `--color-wk-text` / `--color-wk-text-muted` | Title / body text |
| `--radius-wk-md` | Corner radius |

Backgrounds are built with [`color-mix()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix) — a 10% mix of the variant color into the elevated background. This keeps tints visually consistent across themes.

## Customization

Override the default variant in `config/wirekit.php`:

```php
'components' => [
    'alert' => ['variant' => 'warning'],
],
```

## Usage & Conventions

> **Prop conventions** — this component uses one or more of the shared semantic prop names (`intent` / `variant` / `tone` / `surface`). See [Prop naming conventions](/extending/prop-naming-conventions) for the canonical vocabulary, alias matrix, and decision tree.