PhiaUi.Components.ErrorDisplay (phia_ui v0.1.17)

Structured error display components for showing application errors, API failures, and standard HTTP error pages.

Inspired by Ant Design Result, GitHub's error pages, Sentry's error UI, and Vercel's edge error displays.

Pure HEEx — no JavaScript required.

Sub-components

Component	Purpose
`error_display/1`	Structured error box with code, message, and expandable trace
`error_boundary/1`	Error catch container with retry and back actions
`http_error/1`	Styled 404/500/403/503 full-page error with illustration

Structured error (API/runtime error)

<.error_display
  code="PAYMENT_FAILED"
  message="The payment processor declined the charge."
  detail="Card ending in 4242 was declined with reason: insufficient_funds."
/>

Error boundary (with retry)

<.error_boundary :if={@load_error} phx-click-retry="reload_data">
  Failed to load dashboard data.
  <:detail>Check your network connection and try again.</:detail>
</.error_boundary>

HTTP error page

<.http_error status={404} />
<.http_error status={500} message="Something went wrong on our end." />
<.http_error status={403} title="Access denied" message="You don't have permission." />

Summary

Functions

error_boundary(assigns)

Renders an error boundary container with a retry action.

error_display(assigns)

Renders a structured error display box.

http_error(assigns)

Renders a full-page styled HTTP error.

Functions

error_boundary(assigns)

Renders an error boundary container with a retry action.

Use as a fallback UI when a section of your LiveView fails to load data. Wire the retry action to re-trigger your mount or data loading logic.

Example

<.error_boundary :if={@load_error}>
  Failed to load project data.
  <:detail>The server returned a 503 error. Our team has been notified.</:detail>
  <:actions>
    <.button phx-click="retry_load" variant={:outline} size={:sm}>
      <.icon name="refresh-cw" class="h-4 w-4" />
      Try again
    </.button>
    <.button navigate={~p"/"} variant={:ghost} size={:sm}>Go home</.button>
  </:actions>
</.error_boundary>

Attributes

title (:string) - Heading text for the error boundary. Defaults to "Something went wrong".
class (:string) - Additional CSS classes. Defaults to nil.
Global attributes are accepted. HTML attrs forwarded to the root <div>.

Slots

inner_block (required) - Error message text.
detail - Optional additional detail rendered in muted text below the message.
actions - Optional action buttons (retry, back, contact support).

error_display(assigns)

Renders a structured error display box.

Use when you need to surface a specific, identifiable error — API failures, validation errors, runtime exceptions — with enough detail for the user (or developer in dev mode) to understand and potentially resolve the issue.

Example

<.error_display
  code="RATE_LIMIT_EXCEEDED"
  message="Too many requests."
  detail="You have exceeded the limit of 100 requests per minute. Please wait before retrying."
/>

<%!-- Dev mode with stack trace --%>
<.error_display
  :if={@dev_mode}
  message={@exception.message}
  trace={@exception.stack}
/>

Attributes

code (:string) - Optional machine error code (e.g. "PAYMENT_FAILED", "E4042"). Defaults to nil.
message (:string) (required) - Human-readable error message.
detail (:string) - Optional additional detail text. Defaults to nil.
trace (:string) - Optional stack trace or raw error string — shown in an expandable <details> block. Defaults to nil.
variant (:atom) - Visual severity variant. Defaults to :destructive. Must be one of :destructive, :warning, or :default.
class (:string) - Additional CSS classes. Defaults to nil.
Global attributes are accepted. HTML attrs forwarded to the root <div>.

http_error(assigns)

Renders a full-page styled HTTP error.

Provides default titles, messages, and icons for common HTTP error codes. All defaults can be overridden via :title, :message, and :actions slot.

Example

<%!-- In a LiveView error route --%>
<.http_error status={404} />

<%!-- Custom 503 --%>
<.http_error
  status={503}
  title="Under maintenance"
  message="We'll be back shortly. Check our status page."
>
  <:actions>
    <.button href="/status" variant={:outline}>View status</.button>
  </:actions>
</.http_error>

Attributes

status (:integer) (required) - HTTP status code. Controls default title, message, and icon. Must be one of 400, 401, 403, 404, 408, 429, 500, 502, or 503.
title (:string) - Override the default title for this status code. Defaults to nil.
message (:string) - Override the default message for this status code. Defaults to nil.
class (:string) - Additional CSS classes for the root element. Defaults to nil.
Global attributes are accepted. HTML attrs forwarded to the root <div>.

Slots

actions - Call-to-action buttons (e.g. 'Go home', 'Contact support'). Falls back to defaults.