Corex.Toast (Corex v0.1.0-rc.0)

Phoenix implementation of Zag.js Toast.

Replace layout flash groups with <.toast_group> and drive toasts from LiveView or the client API.

Anatomy

Layout flash

<.toast_group id="layout-toast" flash={@flash} class="toast">
  <:loading>
    <.heroicon name="hero-arrow-path" />
  </:loading>
</.toast_group>

Flash defaults

<.toast_group
  id="layout-toast"
  class="toast"
  flash={@flash}
  flash_info={%{title: "Success", type: :success, duration: 5000}}
  flash_error={%{title: "Error", type: :error, duration: :infinity}}
/>

API

Target a toast group by its DOM id on <.toast_group>.

Function	Action	Returns
`create/5`	Create toast (client)	`%Phoenix.LiveView.JS{}`
`create/6`	Create toast (server)	`socket`
`update/3`	Update toast (client)	`%Phoenix.LiveView.JS{}`
`update/4`	Update toast (server)	`socket`
`remove/2`	Remove toast immediately (client)	`%Phoenix.LiveView.JS{}`
`remove/3`	Remove toast immediately (server)	`socket`
`dismiss/2`	Dismiss with lifecycle (client)	`%Phoenix.LiveView.JS{}`
`dismiss/3`	Dismiss with lifecycle (server)	`socket`

create (client)

<.action
  phx-click={Corex.Toast.create("layout-toast", "Info", "Info description", :info, [])}
  class="button button--sm"
>
  Info
</.action>

create (server)

def handle_event("create_info_toast", _, socket) do
  {:noreply,
   Corex.Toast.create(
     socket,
     "layout-toast",
     "Info",
     "Info description",
     :info,
     duration: 5000
   )}
end

create opts: duration, loading: true, id: "stable-id", priority: 1–8, action: map with label, js, optional class.

Style

Target parts with data-scope and data-part, or use Corex Design: import tokens and toast.css, then set class="toast" on <.toast_group>.

[data-scope="toast"][data-part="group"] {}
[data-scope="toast"][data-part="root"] {}
[data-scope="toast"][data-part="title"] {}
[data-scope="toast"][data-part="description"] {}
[data-scope="toast"][data-part="close-trigger"] {}
[data-scope="toast"][data-part="action-trigger"] {}

@import "../corex/main.css";
@import "../corex/tokens/themes/neo/light.css";
@import "../corex/components/toast.css";

Stack modifiers on the group host (class on <.toast_group>).

Color

Modifier	Classes
Default	`toast`
Accent	`toast toast--accent`
Brand	`toast toast--brand`
Alert	`toast toast--alert`
Info	`toast toast--info`
Success	`toast toast--success`

Summary

Components

toast_client_error(assigns)

Renders a div that creates a toast notification when a client error occurs.

toast_connected(assigns)

Renders a div that creates a toast notification when the connection is restored.

toast_disconnected(assigns)

Renders a div that creates a toast notification when the connection is lost.

toast_group(assigns)

Renders a toast group (toaster) that manages multiple toast notifications.

toast_server_error(assigns)

Renders a div that creates a toast notification when a server error occurs.

API

create(toast_group_id, title, description, type, opts)

Append a toast from phx-click. Dispatches toast:create on the toast group host (id). Optional keyword opts: :id, :duration, :loading, :priority, :action.

create(socket, toast_group_id, title, description, type, opts \\ [])

Append a toast from handle_event (toast-create). Payload includes groupId plus Zag fields assembled from the same arguments.

dismiss(toast_group_id, toast_id)

Begin dismiss animation from phx-click. Dispatches toast:dismiss with detail.id.

dismiss(socket, toast_group_id, toast_id)

Begin dismiss animation from handle_event (toast-dismiss).

remove(toast_group_id, toast_id)

Remove a toast immediately from phx-click. Dispatches toast:remove with detail.id.

remove(socket, toast_group_id, toast_id)

Remove a toast immediately from handle_event (toast-remove).

update(toast_group_id, toast_id, attrs)

Patch an existing toast from phx-click. Dispatches toast:update with detail.id and optional fields from attrs (map or keyword list).

update(socket, toast_group_id, toast_id, attrs)

Patch an existing toast from handle_event (toast-update).

Components

toast_client_error(assigns)

Renders a div that creates a toast notification when a client error occurs.

This component should be placed in your layout and will automatically create a toast when Phoenix LiveView detects a client-side connection error.

Anatomy

<.toast_client_error
  toast_group_id="layout-toast"
  title="We can't find the internet"
  description="Attempting to reconnect"
  type={:loading}
  duration={:infinity}
/>

Attributes

id (:string) - Defaults to "client-error-toast".
toast_group_id (:string) (required)
title (:string) (required)
description (:string) - Defaults to nil.
type (:atom) - Defaults to :info. Must be one of :info, :success, or :error.
duration (:any) - Defaults to :infinity.

toast_connected(assigns)

Renders a div that creates a toast notification when the connection is restored.

This component should be placed in your layout and will automatically create a toast when Phoenix LiveView detects that the connection has been restored.

Anatomy

<.toast_connected
  toast_group_id="layout-toast"
  title="Connection restored"
  description="You're back online"
  type={:success}
/>

Attributes

id (:string) - Defaults to "connected-toast".
toast_group_id (:string) (required)
title (:string) (required)
description (:string) - Defaults to nil.
type (:atom) - Defaults to :success. Must be one of :info, :success, or :error.
duration (:any) - Defaults to 5000.

toast_disconnected(assigns)

Renders a div that creates a toast notification when the connection is lost.

This component should be placed in your layout and will automatically create a toast when Phoenix LiveView detects that the connection has been lost.

Anatomy

<.toast_disconnected
  toast_group_id="layout-toast"
  title="Connection lost"
  description="Attempting to reconnect"
  type={:warning}
  duration={:infinity}
/>

Attributes

id (:string) - Defaults to "disconnected-toast".
toast_group_id (:string) (required)
title (:string) (required)
description (:string) - Defaults to nil.
type (:atom) - Defaults to :info. Must be one of :info, :success, or :error.
duration (:any) - Defaults to :infinity.

toast_group(assigns)

Renders a toast group (toaster) that manages multiple toast notifications.

This component should be rendered once in your layout.

Anatomy

 <.toast_group id="layout-toast" class="toast" flash={@flash}>
  <:loading>
    <.heroicon name="hero-arrow-path" />
  </:loading>
</.toast_group>

Flash Messages

You can use the flash attribute to display flash messages as toasts. Optional flash_info and flash_error accept maps with atom keys title, type, and duration for defaults when rendering info and error flashes. The description comes from the Phoenix flash message.

<.toast_group
id="layout-toast"
class="toast"
flash={@flash}
flash_info={%{title: "Success", type: :success, duration: 5000}}
flash_error={%{title: "Error", type: :error, duration: :infinity}}/>

Attributes

id (:string) (required) - The id of the toast group.
placement (:string) - Where toasts appear on screen. Defaults to "bottom-end". Must be one of "top-start", "top", "top-end", "bottom-start", "bottom", or "bottom-end".
overlap (:boolean) - Whether toasts can overlap. Defaults to true.
max (:integer) - Maximum number of visible toasts. Defaults to 5.
gap (:integer) - Gap between toasts in pixels. Defaults to nil.
offset (:string) - Offset from viewport edge. Defaults to nil.
pause_on_page_idle (:boolean) - Pause duration when page is idle. Defaults to false.
flash (:map) - The map of flash messages to display as toasts. Defaults to %{}.
flash_info (:any) - Defaults for :info flashes: Corex.Flash.Info, map, or omit for translation defaults. Defaults to nil.
flash_error (:any) - Defaults for :error flashes: Corex.Flash.Error, map, or omit for translation defaults. Defaults to nil.
translation (Corex.Toast.Translation) - Override default titles for info/error flash messages. Defaults to nil.
Global attributes are accepted.

Slots

loading - the loading spinner icon to display when duration is infinity. Accepts attributes:
- class (:string)
close - content placed in each toast close button (hidden template, cloned in the client).

toast_server_error(assigns)

Renders a div that creates a toast notification when a server error occurs.

This component should be placed in your layout and will automatically create a toast when Phoenix LiveView detects a server-side connection error.

Anatomy

<.toast_server_error
  toast_group_id="layout-toast"
  title="Something went wrong!"
  description="Attempting to reconnect"
  type={:error}
  duration={:infinity}
/>

Attributes

id (:string) - Defaults to "server-error-toast".
toast_group_id (:string) (required)
title (:string) (required)
description (:string) - Defaults to nil.
type (:atom) - Defaults to :error. Must be one of :info, :success, or :error.
duration (:any) - Defaults to :infinity.

API

create(toast_group_id, title, description, type, opts)

Append a toast from phx-click. Dispatches toast:create on the toast group host (id). Optional keyword opts: :id, :duration, :loading, :priority, :action.

<.action phx-click={Corex.Toast.create("toast-group-id", "Saved", "Draft stored.", :info, duration: 4_000)}>Notify</.action>
<.toast_group id="toast-group-id" placement="bottom-end" />

document.getElementById("toast-group-id")?.dispatchEvent(
  new CustomEvent("toast:create", {
    bubbles: true,
    detail: { title: "Saved", description: "OK.", type: "info", duration: 4000 },
  })
);

create(socket, toast_group_id, title, description, type, opts \\ [])

Append a toast from handle_event (toast-create). Payload includes groupId plus Zag fields assembled from the same arguments.

def handle_event("notify", _, socket) do
  {:noreply, Corex.Toast.create(socket, "toast-group-id", "Done", "Completed.", :success, duration: 3_000)}
end

dismiss(toast_group_id, toast_id)

Begin dismiss animation from phx-click. Dispatches toast:dismiss with detail.id.

<.action phx-click={Corex.Toast.dismiss("toast-group-id", @toast_id)}>Dismiss</.action>
<.toast_group id="toast-group-id" />

dismiss(socket, toast_group_id, toast_id)

Begin dismiss animation from handle_event (toast-dismiss).

def handle_event("fade_out", %{"id" => id}, socket) do
  {:noreply, Corex.Toast.dismiss(socket, "toast-group-id", id)}
end

remove(toast_group_id, toast_id)

Remove a toast immediately from phx-click. Dispatches toast:remove with detail.id.

<.action phx-click={Corex.Toast.remove("toast-group-id", @toast_id)}>Remove</.action>
<.toast_group id="toast-group-id" />

remove(socket, toast_group_id, toast_id)

Remove a toast immediately from handle_event (toast-remove).

def handle_event("drop_toast", %{"id" => id}, socket) do
  {:noreply, Corex.Toast.remove(socket, "toast-group-id", id)}
end

update(toast_group_id, toast_id, attrs)

Patch an existing toast from phx-click. Dispatches toast:update with detail.id and optional fields from attrs (map or keyword list).

<.action phx-click={Corex.Toast.update("toast-group-id", @toast_id, title: "Uploading…", loading: true)}>Update</.action>
<.toast_group id="toast-group-id" />

update(socket, toast_group_id, toast_id, attrs)

Patch an existing toast from handle_event (toast-update).

def handle_event("patch_toast", %{"id" => id}, socket) do
  {:noreply, Corex.Toast.update(socket, "toast-group-id", id, %{title: "Finished", loading: false})}
end