LineaUI.Components.Toast (linea_ui v0.1.1)

Copy Markdown View Source

LineOne's notifications: a small colored note at a corner or an edge of the screen that leaves by itself after a few seconds.

Mount the toaster once, in the layout every LiveView renders (it reads the flash):

<.toaster flash={@flash} />

Then, from the server:

conn |> put_toast("Saved", color: "success") |> redirect(to: ~p"/orders")
socket |> put_toast("Saved", color: "success") |> push_navigate(to: ~p"/orders")
socket |> send_toast("Copied", color: "info", position: "center-top")

put_toast/3 goes through the flash, so it survives a redirect; send_toast/3 pushes the toast to the page at once. From the browser, without a round trip:

<.button phx-click={show_toast("This is a simple notification", color: "primary")}>Primary</.button>

Options: color (neutral primary secondary info success warning error light dark), position (left-top left-bottom center-top center-bottom right-top right-bottom), duration in milliseconds (0 keeps it until closed), close (a close button) and template, the id of a <template> on the page whose first element is shown instead of the message (an element with data-toast-dismiss inside it closes the toast).

The toasts of a corner are stacked: the newest is shown in full and the older ones sit behind it, smaller, as slivers (three at most). With the pointer over the stack it opens, every toast in its own size, and their timers wait; when the pointer leaves they go on with the time they had left. Set stack={false} on the toaster to keep them always open, one above the other.

Summary

Functions

Leaves a toast in the flash of a Plug.Conn (after fetch_flash) or a LiveView socket. The toaster shows it on the next page, so it survives redirect/2, push_navigate/2 and push_patch/2. Several calls pile up.

Shows a toast now, from handle_event/3 or handle_info/2: it is pushed to the page as the linea:toast event, which the toaster's hook handles.

A %JS{} that shows a toast in the browser, without a round trip. Takes the same options as put_toast/3.

The colors a toast takes.

The positions a toast takes.

The place the toasts are drawn. Mount it once per page, inside the LiveView (the layout that receives @flash).

Functions

put_toast(conn_or_socket, message, opts \\ [])

Leaves a toast in the flash of a Plug.Conn (after fetch_flash) or a LiveView socket. The toaster shows it on the next page, so it survives redirect/2, push_navigate/2 and push_patch/2. Several calls pile up.

send_toast(socket, message, opts \\ [])

Shows a toast now, from handle_event/3 or handle_info/2: it is pushed to the page as the linea:toast event, which the toaster's hook handles.

show_toast(message)

@spec show_toast(String.t() | nil) :: Phoenix.LiveView.JS.t()

A %JS{} that shows a toast in the browser, without a round trip. Takes the same options as put_toast/3.

show_toast(js, message)

@spec show_toast(
  Phoenix.LiveView.JS.t() | String.t() | nil,
  String.t() | keyword() | nil
) ::
  Phoenix.LiveView.JS.t()

show_toast(js, message, opts)

@spec show_toast(Phoenix.LiveView.JS.t(), String.t() | nil, keyword()) ::
  Phoenix.LiveView.JS.t()

toast_colors()

@spec toast_colors() :: [String.t()]

The colors a toast takes.

toast_positions()

@spec toast_positions() :: [String.t()]

The positions a toast takes.

toaster(assigns)

The place the toasts are drawn. Mount it once per page, inside the LiveView (the layout that receives @flash).

Attributes

  • id (:string) - Defaults to "linea-toaster".
  • flash (:map) - The @flash, where put_toast/3 leaves its toasts. Defaults to %{}.
  • position (:string) - The default position. Defaults to "right-bottom". Must be one of "left-top", "left-bottom", "center-top", "center-bottom", "right-top", or "right-bottom".
  • duration (:integer) - The default duration, in milliseconds. Defaults to 5000.
  • stack (:boolean) - Pile the toasts of a corner behind the newest and open the pile under the pointer. Defaults to true.
  • close_label (:string) - Defaults to "Close".
  • Global attributes are accepted.