Elemental.Feedback.Toast (elemental v0.3.1)

An abstraction built on top of Daisy's toast component for building toast messages, flash messages, and more.

Provides a set of dead/stateless components for use to operate displaying informative messages, with a simplified API that augments Phoenix' flashes.

Usage

The most bare bones component provided is the toast/1 component which is meant as a building block container for placing toasts generally speaking based on Daisy's toast component

<.toast>
  You toast content here
</.toast>

For toast message use cases we provide the toast_group/1 component which given a list of messages will display them stacked in a toast/1 component under the Elemental.Feedback.Alert.alert/1 component.

<.toast_group messages={["Some message"]} />

Additionally we provide a compatibility component flash_group/1 as a drop in for Phoenix' generated component

<.flash_group flash={@flash} />

Live component

We provide a live/stateful component for toast groups under Elemental.Feedback.Live.ToastGroup, this can be accessed by passing the live attribute to toast_group/1

<.toast_group live />

The live variant allows for sending messages from the server side programmatically/dynamically.

Summary

Functions

Drop in for Phoenix' flash group.

The primary toast component, this guarantees a content to be displayed in the provided placement on the page.

Provides an abstraction on top of toast/1 for displaying a list alerts for the user. Relies on Elemental.Feedback.Alert.alert/1 for rendering the specific messages under the hood.

Functions

flash_group(assigns)

Drop in for Phoenix' flash group.

Attributes

  • id (:string) - Defaults to nil.
  • flash (:map) (required)

toast(assigns)

The primary toast component, this guarantees a content to be displayed in the provided placement on the page.

This is meant more as a building block for composing more complete/complex toast messages/overlays.

You probably want to use toast_group/1 if you want to display simple messages.

Caveat

Note that if you place two toasts with the same placement there will be no guarantee from the component on which comes on top, probably the second to show in the DOM tree will.

This is by design as it's intended to use one toast per placement (or even per page).

Attributes

  • id (:string) - Defaults to "toast".
  • placement (:string) - The positioning of the toast stack. Defaults to "top-end".
  • Global attributes are accepted.

Slots

  • inner_block (required)

toast_group(assigns)

Provides an abstraction on top of toast/1 for displaying a list alerts for the user. Relies on Elemental.Feedback.Alert.alert/1 for rendering the specific messages under the hood.

This component is intended for building toast/flash messaging systems.

This component doesn't respect Phoenix' default flashes API by default, however you can pass Phoenix' flash into the flash attribute to display Phoenix' flashes inlined, immediately after normal messages. For a more seamless integration you can use the flash_group/1 component.

Caveats

Inherent to the toast/1 component which this component is built of, it won't play nice to having another toast group with messages overlapping it and the behaviour won't be controlled by Elemental in such cases.

If you want to have multiple toast groups on the same placement you're better off building on top of toast/1 directly instead.

Phoenix flash system integration

To allow seamless interoperability with Phoenix' flash system, if passed Phoenix' flash messages via the flash attribute.

Any message originating from Phoenix' flash system will ignore the any provided value for on-clear and instead send the Phoenix event of lv:clear-flash.

Also, messages originating from Phoenix' flash subsystem will be rendered immediately after the messages formatted via Elemental.Feedback.Toast.toast_group/1 and in an identical styling via the Elemental.Feedback.Alert.alert/1 component.

Phoenix' client and server errors

This component will display Phoenix' client and server errors by default, these errors are non-closeable and will stay until the client side reconnects properly with the server side. This can be controlled by the phoenix-errors attribute. Note these messages won't trigger on-clear events when disappearing.

Attributes

  • id (:string) - The ID used for the toast group component. Defaults to "toast-group".

  • live (:boolean) - Enables the LiveComponent to be rendered in place of the stateless/dead component which is the default.

    If enabled you can use Elemental.Feedback.Live.ToastGroup module to interact dynamically with the toast group and send messages from the server side dynamically.

    Enabling this disables support for passing messages, on-clear and the global attributes.

    Defaults to false.

  • messages (:any) - The list of messages to display in the group, ignored if live is enabled. Required otherwise.

    Type

    Accepts either a list or a Phoenix.LiveView.LiveStream, with each item standing for a message and must be one type as one of the following;

    1. String.t indicating the message is simply some text context to display. No title is displayed for it and it will be shown in the default alert style.
    2. {String.t, String.t} indicating a message where the first item is the alert type to use, as defined in Elemental.Feedback.Alert.alert/1, and the second is the message content itself. The alert level/type will be used as title.
    3. {String.t, String.t, String.t} indicating a message where the first item is the alert type to use, as defined in Elemental.Feedback.Alert.alert/1, the second is the message's title to display, and the third indicating the message content itself.

    Mixing those types is in one list of messages is allowed an will be normalized.

    This list of messages can also be provided from a LiveView stream, where each item coming from the stream must respect the defined typings for the message items.

  • flash (:map) - In order to provide compatibility with Phoenix' flash subsystem we accept a flash attribute as defined by Phoenix and do render it right after the messages passed in Elemental.Feedback.Toast.toast_group/1 style.

    Flash messages will ignore the on-clear and phx-target and instead emit an lv:clear-flash event when cleared without a predefined target. This is to stay inline with how Phoenix expects those to behave.

    Defaults to %{}.

  • placement (:string) - The positioning of the toast stack. Defaults to "top-end".

  • on-clear (:string) - The event to emit on closing of an alert

    Ignored if live is enabled.

    Defaults to nil.

  • phoenix-errors (:boolean) - Controls showing Phoenix' client and server errors. Defaults to true.

  • outline (:boolean) - Render the alert in an outline style. Defaults to false.

  • dash (:boolean) - Render the alert in dash style. Defaults to false.

  • soft (:boolean) - Render the alert in soft style. Defaults to false.