PhiaUi.Components.Alert (phia_ui v0.1.17)

Copy Markdown View Source

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

ComponentElementPurpose
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

VariantBackground / borderTypical use cases
:defaultNeutral backgroundGeneral info, tips, feature announcements
:destructiveRed tintErrors, failed operations, danger warnings
:warningYellow tint (light/dark)Caution, non-critical issues, expiry notices
:successGreen 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.

Summary

Functions

alert(assigns)

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

alert_action(assigns)

Renders an inline action button inside the alert.

alert_description(assigns)

Renders the alert supporting text in muted, small type.

alert_title(assigns)

Renders the alert heading in bold with tight leading.

Functions

alert(assigns)

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(assigns)

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(assigns)

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(assigns)

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.