# Alert

Alerts **surface important feedback** inline—errors, confirmations, or contextual help. Use **`label`** / **`text`** for simple copy, or the **default slot** for rich content (links, buttons). Set **`announce`** when the message appears after an action so screen readers pick it up.

## Basic example

<sonic-code>
  <template>
    <sonic-alert status="error" label="Gate change" text="CN 001 now departs from gate B12" background></sonic-alert>
  </template>
</sonic-code>

## Status

Color and icon follow `status`. With no `status`, behavior is `default`.

<sonic-code>
  <template>
    <div class="grid gap-4">
      <sonic-alert label="Default">CN 001 · CDG → JFK.</sonic-alert>
      <sonic-alert status="success" label="Success">CN 001 has landed at JFK.</sonic-alert>
      <sonic-alert status="error" label="Error">CN 001 is cancelled.</sonic-alert>
      <sonic-alert status="warning" label="Warning">Turbulence expected over the Atlantic.</sonic-alert>
      <sonic-alert status="info" label="Info">Boarding starts in 20 minutes.</sonic-alert>
    </div>
  </template>
</sonic-code>

## Accessibility (`announce`)

By default, an alert already in the DOM is **not** announced (no `role` / `aria-live`). Set **`announce`** when the message appears **after** user action (API response, validation, etc.): screen readers get `role="alert"` for `error`, otherwise `role="status"` and `aria-live="polite"`.

`sonic-alert-messages` sets `announce` on every rendered alert.

<sonic-code>
  <template>
    <sonic-alert announce status="success" label="Checked in" text="Your boarding pass is ready."></sonic-alert>
  </template>
</sonic-code>

## Content and icon

`label` and `text` accept plain text only. The default slot is rendered after `text`. Use the **`icon`** slot to replace the default `sonic-icon`. **`noIcon`** hides the icon.

<sonic-code>
  <template>
    <sonic-alert status="info" noIcon label="No icon" text="Cruising altitude reached."></sonic-alert>
  </template>
</sonic-code>

## Custom icon slot

Project any markup into **`slot="icon"`** (icon, image, custom component). Keep it decorative with `aria-hidden="true"` when the message text already conveys meaning.

<sonic-code>
  <template>
    <sonic-alert status="success" label="Upgrade confirmed" background>
      <sonic-icon slot="icon" library="iconoir" name="trophy" aria-hidden="true"></sonic-icon>
      You are now seated in first class.
    </sonic-alert>
  </template>
</sonic-code>

## Size

Default size is `md` (omit the `size` attribute). `inherit` follows the parent font size.

<sonic-code>
  <template>
    <div class="grid gap-4">
      <sonic-alert status="error" label="Delayed" size="2xs">
        CN 001 departure moved to 18:40.
      </sonic-alert>
      <sonic-alert status="error" label="Delayed" size="xs">
        CN 001 departure moved to 18:40.
      </sonic-alert>
      <sonic-alert status="error" label="Delayed" size="sm">
        CN 001 departure moved to 18:40.
      </sonic-alert>
      <sonic-alert status="error" label="Delayed">
        CN 001 departure moved to 18:40.
      </sonic-alert>
      <sonic-alert status="error" label="Delayed" size="lg">
        CN 001 departure moved to 18:40.
      </sonic-alert>
      <sonic-alert status="error" label="Delayed" size="xl">
        CN 001 departure moved to 18:40.
      </sonic-alert>
      <sonic-alert status="error" label="Delayed" size="2xl">
        CN 001 departure moved to 18:40.
      </sonic-alert>
    </div>
  </template>
</sonic-code>

## Alert with link

Rich content in the slot (buttons, links).

<sonic-code>
  <template>
    <sonic-alert status="info" label="Gate change">
      CN 001 now departs from gate B12<br />
      <div class="flex gap-2 mt-1">
        <sonic-button variant="outline" type="info" size="xs">View flight</sonic-button>
        <sonic-button variant="ghost" type="info" size="xs">Dismiss</sonic-button>
      </div>
    </sonic-alert>
  </template>
</sonic-code>

## Background

Tinted background from the `status` color (`color-mix` on `currentColor`).

<sonic-code>
  <template>
    <div class="grid gap-4">
      <sonic-alert background label="Flight update">Boarding is now open at gate B12.</sonic-alert>
      <sonic-alert status="success" background label="Flight update">
        Boarding is now open at gate B12.
      </sonic-alert>
      <sonic-alert status="error" background label="Flight update">
        Boarding is now open at gate B12.
      </sonic-alert>
      <sonic-alert status="warning" background label="Flight update">
        Boarding is now open at gate B12.
      </sonic-alert>
      <sonic-alert status="info" background label="Flight update">
        Boarding is now open at gate B12.
      </sonic-alert>
    </div>
  </template>
</sonic-code>

## Dismissible

`dismissible` removes the alert from the DOM when the close control is clicked (i18n aria label). **`dismissible`** and **`background`** are independent: without `background`, close sits at the end of the row; with `background`, top-right.

<sonic-code>
  <template>
    <sonic-alert status="info" class="mb-3" dismissible label="Baggage claim moved to belt 4.">
    </sonic-alert>
    <sonic-alert class="mb-3" dismissible background label="Flight update">
      Boarding is now open at gate B12.
    </sonic-alert>
  </template>
</sonic-code>

## Dismiss forever

With **`dismissForever`**, dismissal is stored in `localStorage` (key `sonic-alert-dismissed`). A stable **`id`** on the element is **required**; without `id`, a warning is logged and nothing is persisted.

<sonic-code>
  <template>
    <sonic-alert
      class="mb-3"
      dismissible
      background
      dismissForever
      label="Flight update"
      id="addressUniqueId"
    >
      Boarding is now open at gate B12.
    </sonic-alert>
  </template>
</sonic-code>

## API reference

| Attribute | Values | Description |
|----------|---------|-------------|
| `status` | `default` (default) · `info` · `success` · `warning` · `error` | Color and default icon |
| `label` | string | Title (plain text) |
| `text` | string | Short body (plain text), rendered before the slot |
| `size` | `2xs` … `2xl` (default `md`) · `inherit` | Corner radius and typography |
| `background` | boolean | Tinted background (`color-mix` on status color) |
| `dismissible` | boolean | Close control; removes the element from the DOM |
| `dismissForever` | boolean | Persists dismissal in `localStorage`; requires **`id`** |
| `noIcon` | boolean | Hides the icon (including custom `icon` slot content) |
| `announce` | boolean | `role="alert"` / `aria-live` for dynamically injected content |

| Slot | Description |
|------|-------------|
| *(default)* | Message body (HTML, actions); rendered after `text` |
| `icon` | Replaces the default `sonic-icon` |