PUI.Flash (pui v1.0.0-beta.8)

Toast notification system for LiveView applications.

Basic Setup

Add the flash group to your layout:

<PUI.Flash.flash_group flash={@flash} />

For LiveView pages with dynamic flashes:

<PUI.Flash.flash_group flash={@flash} live={true} />

Sending Flashes

From a LiveView:

PUI.Flash.send_flash("Operation completed successfully!")

With custom options:

PUI.Flash.send_flash(%PUI.Flash.Message{
  type: :success,
  message: "Saved!",
  duration: 8,
  class: "border-green-500"
})

Positioning

Position the flash container in different corners:

<PUI.Flash.flash_group flash={@flash} position="top-right" />
<PUI.Flash.flash_group flash={@flash} position="top-center" />
<PUI.Flash.flash_group flash={@flash} position="bottom-left" />

Available positions: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right

Custom Content

Send HEEx content in flashes:

PUI.Flash.send_flash(~H|<div class="flex items-center gap-2">
  <.icon name="hero-check-circle" class="size-5" />
  <span>Success!</span>
</div>|)

Updating Flashes

Update an existing flash by ID:

PUI.Flash.update_flash(%PUI.Flash.Message{
  id: "my-flash",
  message: "Updated!"
})

Configuration

Attribute	Type	Default	Description
`flash`	`map`	required	Phoenix flash map
`live`	`boolean`	`false`	Enable LiveComponent for dynamic updates
`position`	`string`	`"top-center"`	Container position
`limit`	`integer`	`5`	Maximum number of visible flashes
`auto_dismiss`	`integer`	`5000`	Auto-dismiss delay in ms
`show_close`	`boolean`	`true`	Show close button

Message Struct

Create flash messages with the Message struct:

%PUI.Flash.Message{
  message: "Hello!",           # Required
  type: :info,                  # :info, :success, :warning, :error
  duration: 5,                  # Seconds until auto-dismiss
  auto_dismiss: true,           # Auto-dismiss enabled
  dismissable: true,            # Allow manual dismiss
  show_close: true,             # Show close button
  class: ""                     # Additional CSS classes
}

Summary

Functions

container(assigns)

Flash container with positioning support.

flash(assigns)

Individual flash message component.

flash_group(assigns)

Use .flash_group to place flash container in your layout.

handle_event(binary, map, socket)

Callback implementation for Phoenix.LiveComponent.handle_event/3.

mount(socket)

Callback implementation for Phoenix.LiveComponent.mount/1.

render(assigns)

Callback implementation for Phoenix.LiveComponent.render/1.

send_flash(pid \\ self(), message)

update(assigns, socket)

Callback implementation for Phoenix.LiveComponent.update/2.

update_flash(pid \\ self(), flash)

Functions

container(assigns)

Flash container with positioning support.

Attributes

position (:string) - Defaults to "top-center".
Global attributes are accepted.

Slots

inner_block

flash(assigns)

Individual flash message component.

Attributes

id (:string)
position (:string) - Defaults to "top-center".
class (:string) - Defaults to "".
show_close (:boolean) - Defaults to true.
Global attributes are accepted.

Slots

inner_block

flash_group(assigns)

Use .flash_group to place flash container in your layout.

If you want to use in liveview page, pass option live={true}

example:

<PUI.Flash.flash_group flash={@flash} live={true}>

Attributes

flash (:map) (required)
live (:boolean) - Defaults to false.
limit (:integer) - Defaults to 5.
position (:string) - Defaults to "top-center". Must be one of "top-left", "top-right", "top-center", "bottom-left", "bottom-right", or "bottom-center".
auto_dismiss (:integer) - Defaults to 5000.
show_close (:boolean) - Defaults to true.

handle_event(binary, map, socket)

Callback implementation for Phoenix.LiveComponent.handle_event/3.

mount(socket)

Callback implementation for Phoenix.LiveComponent.mount/1.

render(assigns)

Callback implementation for Phoenix.LiveComponent.render/1.

send_flash(pid \\ self(), message)

update(assigns, socket)

Callback implementation for Phoenix.LiveComponent.update/2.

update_flash(pid \\ self(), flash)