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
Drop in for Phoenix' flash group.
Attributes
id
(:string
) - Defaults tonil
.flash
(:map
) (required)
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)
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 iflive
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;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.{String.t, String.t}
indicating a message where the first item is the alert type to use, as defined inElemental.Feedback.Alert.alert/1
, and the second is the message content itself. The alert level/type will be used as title.{String.t, String.t, String.t}
indicating a message where the first item is the alert type to use, as defined inElemental.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 inElemental.Feedback.Toast.toast_group/1
style.Flash messages will ignore the
on-clear
andphx-target
and instead emit anlv: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 alertIgnored if
live
is enabled.Defaults to
nil
.phoenix-errors
(:boolean
) - Controls showing Phoenix' client and server errors. Defaults totrue
.outline
(:boolean
) - Render the alert in an outline style. Defaults tofalse
.dash
(:boolean
) - Render the alert in dash style. Defaults tofalse
.soft
(:boolean
) - Render the alert in soft style. Defaults tofalse
.