SutraUI.Toast (Sutra UI v0.3.0)

View Source

Toast notification component for displaying temporary messages.

Toasts provide brief, non-blocking notifications that automatically disappear. Use them for success confirmations, error alerts, or informational messages that don't require user action.

Examples

# Using with Phoenix flash (most common)
<.toast_container flash={@flash} />

# In your LiveView, use put_flash
def handle_event("save", params, socket) do
  case save_data(params) do
    {:ok, _} ->
      {:noreply, put_flash(socket, :info, "Changes saved successfully")}
    {:error, _} ->
      {:noreply, put_flash(socket, :error, "Failed to save changes")}
  end
end

# Programmatic toast via push_event
def handle_event("complete", _params, socket) do
  {:noreply,
   socket
   |> push_event("toast", %{
     variant: "success",
     title: "Task Complete",
     description: "Your export is ready for download.",
     duration: 5000
   })}
end

# Individual toast (for custom layouts)
<.toast id="custom-toast" variant="success">
  <:title>Upload Complete</:title>
  <:description>Your file has been uploaded successfully.</:description>
  <:action>
    <.button size="sm" variant="outline">View File</.button>
  </:action>
</.toast>

Components

ComponentDescription
toast_container/1Container that displays flash messages
toast/1Individual toast notification

Variants

VariantUsageAppearance
defaultGeneral informationNeutral styling
successSuccessful actionsGreen/success color
destructiveErrors and failuresRed/danger color

Programmatic Toasts

Send toasts from your LiveView using push_event:

push_event(socket, "toast", %{
  variant: "success",     # "default", "success", or "destructive"
  title: "Title text",    # Required
  description: "Details", # Optional
  duration: 5000          # Auto-dismiss in ms (0 = manual only)
})

The .ToastContainer hook listens for the toast event and creates toast elements dynamically.

Toast Slots

SlotDescription
titleMain toast message
descriptionAdditional detail text
actionOptional action button

Auto-Dismissal

  • Flash-based toasts: Cleared when user navigates or clicks close
  • Programmatic toasts: Auto-dismiss after duration milliseconds
  • Set duration: 0 for toasts that require manual dismissal

Colocated Hook

The .ToastContainer hook handles:

  • Listening for toast push events
  • Creating toast elements dynamically
  • Animating show/hide transitions
  • Auto-dismissal timers

See JavaScript Hooks for more details.

Accessibility

  • Uses role="status" for non-critical notifications
  • Uses aria-live="polite" for screen reader announcements
  • Close button has aria-label="Close"
  • Focus is not stolen from current context

Screen Reader Behavior

Toasts use aria-live="polite" which waits for the user to pause before announcing. This prevents interrupting ongoing screen reader speech. For critical alerts that must interrupt, use SutraUI.Alert with role="alert" instead.

Summary

Functions

toast(assigns)

Renders an individual toast notification.

toast_container(assigns)

Renders a toast container that displays flash messages.

Functions

toast(assigns)

Renders an individual toast notification.

Examples

<.toast variant="success">
  <:title>Success!</:title>
  <:description>Your changes have been saved.</:description>
</.toast>

Attributes

  • id (:string) (required) - Unique identifier for the toast.
  • variant (:string) - The visual variant. Defaults to "default". Must be one of "default", "success", or "destructive".
  • class (:string) - Additional CSS classes. Defaults to nil.
  • Global attributes are accepted. Additional HTML attributes. Supports all globals plus: ["role", "aria-live"].

Slots

  • title - The toast title.
  • description - Optional description text.
  • action - Optional action button.

toast_container(assigns)

Renders a toast container that displays flash messages.

Examples

<.toast_container flash={@flash} />

Attributes

  • flash (:map) (required) - The flash map from the socket.
  • class (:string) - Additional CSS classes. Defaults to nil.