# `PhiaUi.Components.Alert`
[🔗](https://github.com/charlenopires/PhiaUI/blob/v0.1.17/lib/phia_ui/components/feedback/alert.ex#L1)

Inline feedback alert for communicating status, errors, and warnings.

Provides 4 semantic variants following the shadcn/ui Alert anatomy. Alerts
are inline, static components — they appear in the document flow and do not
auto-dismiss. For transient notifications that appear and disappear
automatically, use `PhiaUi.Components.Toast` instead.

Pure HEEx — no JavaScript required.

## Sub-components

| Component           | Element    | Purpose                                         |
|---------------------|------------|-------------------------------------------------|
| `alert/1`           | `<div>`    | Root container with `role="alert"`              |
| `alert_title/1`     | `<p>`      | Bold heading inside the alert                   |
| `alert_description/1`| `<p>`     | Muted supporting text                           |
| `alert_action/1`    | `<button>` | Inline action (dismiss, renew, learn more, etc.)|

## Variants

| Variant        | Background / border        | Typical use cases                              |
|----------------|----------------------------|------------------------------------------------|
| `:default`     | Neutral background         | General info, tips, feature announcements      |
| `:destructive` | Red tint                   | Errors, failed operations, danger warnings     |
| `:warning`     | Yellow tint (light/dark)   | Caution, non-critical issues, expiry notices   |
| `:success`     | Green tint (light/dark)    | Successful operations, confirmations           |

## Informational alert

    <.alert>
      <.alert_title>Heads up</.alert_title>
      <.alert_description>
        You can configure this in your account settings.
      </.alert_description>
    </.alert>

## Destructive / error alert

    <.alert variant={:destructive}>
      <:icon><.icon name="circle-x" /></:icon>
      <.alert_title>Something went wrong</.alert_title>
      <.alert_description>
        We couldn't save your changes. Please try again.
      </.alert_description>
    </.alert>

## Warning alert with action

    <.alert variant={:warning}>
      <:icon><.icon name="triangle-alert" /></:icon>
      <.alert_title>Your session is about to expire</.alert_title>
      <.alert_description>
        You will be logged out in 5 minutes due to inactivity.
      </.alert_description>
      <.alert_action phx-click="renew_session">Stay logged in</.alert_action>
    </.alert>

## Success alert after form submit

    <.alert variant={:success}>
      <:icon><.icon name="circle-check" /></:icon>
      <.alert_title>Payment confirmed</.alert_title>
      <.alert_description>
        Your invoice has been sent to {@user.email}.
      </.alert_description>
    </.alert>

## Inline form validation alert

    <%= if @form.errors != [] do %>
      <.alert variant={:destructive}>
        <:icon><.icon name="circle-x" /></:icon>
        <.alert_title>Please fix the following errors</.alert_title>
        <.alert_description>
          <ul class="mt-1 list-disc list-inside space-y-0.5">
            <%= for {field, {message, _}} <- @form.errors do %>
              <li>{Phoenix.Naming.humanize(field)}: {message}</li>
            <% end %>
          </ul>
        </.alert_description>
      </.alert>
    <% end %>

## Deprecation / maintenance notice

    <.alert>
      <:icon><.icon name="info" /></:icon>
      <.alert_title>Scheduled maintenance</.alert_title>
      <.alert_description>
        The platform will be unavailable on Saturday, March 8 from 2–4 AM UTC.
      </.alert_description>
      <.alert_action href="/status">View status page</.alert_action>
    </.alert>

## Accessibility

- The root `<div>` carries `role="alert"` so assistive technologies
  announce newly rendered alerts immediately (live region behaviour).
- For alerts that should not interrupt the user mid-task, use
  `role="status"` by passing `rest={%{role: "status"}}`.
- The `:icon` slot's icon should not carry an accessible name (it is
  decorative); the title and description provide the textual context.

# `alert`

Renders a styled alert container with `role="alert"` for screen readers.

Use `alert_title/1`, `alert_description/1`, and optionally `alert_action/1`
as the inner content. Provide an `:icon` slot for a leading icon.

## Example

    <.alert variant={:warning}>
      <:icon><.icon name="triangle-alert" /></:icon>
      <.alert_title>Billing required</.alert_title>
      <.alert_description>
        Add a payment method to continue using the service.
      </.alert_description>
      <.alert_action phx-click="open_billing">Add payment</.alert_action>
    </.alert>

## Attributes

* `variant` (`:atom`) - Visual and semantic variant. Use `:destructive` for errors, `:warning` for cautions, `:success` for confirmations, `:default` for general info. Defaults to `:default`. Must be one of `:default`, `:destructive`, `:warning`, or `:success`.
* `class` (`:string`) - Additional CSS classes merged via `cn/1`. Defaults to `nil`.
* Global attributes are accepted. HTML attributes forwarded to the root `<div>` element. Use `role="status"` to override the default `role="alert"` for non-urgent messages.
## Slots

* `icon` - Optional leading icon, e.g. `<.icon name="circle-alert" />`. Positioned absolutely at the top-left. The icon colour automatically matches the variant via `[&>svg]:text-current`.
* `inner_block` (required) - Alert body. Typically `alert_title/1` followed by `alert_description/1`. May also include `alert_action/1`.

# `alert_action`

Renders an inline action button inside the alert.

Use for common alert actions such as dismissing the message, navigating
to a related page, or triggering a remediation flow.

## Examples

    <%!-- Session expiry warning with renew action --%>
    <.alert variant={:warning}>
      <.alert_title>Session expiring</.alert_title>
      <.alert_description>You'll be logged out in 5 minutes.</.alert_description>
      <.alert_action phx-click="renew_session">Stay logged in</.alert_action>
    </.alert>

    <%!-- Error with retry action --%>
    <.alert variant={:destructive}>
      <.alert_title>Upload failed</.alert_title>
      <.alert_description>The file exceeds the 10 MB limit.</.alert_description>
      <.alert_action phx-click="retry_upload">Try again</.alert_action>
    </.alert>

## Attributes

* `class` (`:string`) - Additional CSS classes applied to the `<button>` element. Defaults to `nil`.
* Global attributes are accepted. HTML attributes forwarded to the `<button>` element. Use `phx-click` for LiveView events or pass `href` for navigation.
## Slots

* `inner_block` (required) - Action label text (e.g. `"Dismiss"`, `"Learn more"`, `"Renew"`).

# `alert_description`

Renders the alert supporting text in muted, small type.

Follows the title and provides additional context. Can contain plain text,
links, or simple lists.

## Example

    <.alert_description>
      Your account has been locked after 5 failed login attempts.
      Contact support to regain access.
    </.alert_description>

## Attributes

* `class` (`:string`) - Additional CSS classes applied to the description `<p>` element. Defaults to `nil`.
## Slots

* `inner_block` (required) - Description text or content. Rendered in small muted type.

# `alert_title`

Renders the alert heading in bold with tight leading.

Styled with `font-medium leading-none tracking-tight` to match the visual
hierarchy established by shadcn/ui. Place this as the first child of the
`alert/1` component.

## Example

    <.alert_title>Account suspended</.alert_title>

## Attributes

* `class` (`:string`) - Additional CSS classes applied to the title `<p>` element. Defaults to `nil`.
## Slots

* `inner_block` (required) - Title text. Keep it short — typically 3–8 words.

---

*Consult [api-reference.md](api-reference.md) for complete listing*