API Notification flashes

This page explains how to implement notification flashes for confirmations, errors or warnings.

Placing flashes into the layout

In your application layout, place an empty element with an [up-flashes] attribute. This indicates where future flash messages should be inserted.

A popular place for flashes is outside your main element:

<nav>
  Navigation items ...
</nav>
<div up-flashes></div> <!-- mark-line -->
<main>
  Main page content ...
</main>

Flashes inside the main element

For styling reasons you may also wish to place the [up-flashes] container inside your main element:

<nav>
  Navigation items ...
</nav>
<main>
  <div up-flashes></div> <!-- mark-line -->
  
  Main page content ...
</main>

This style will usually cause multiple [up-flashes] containers to be attached when you open an overlay. In this case any flash messages from overlay content will be rendered into the overlay preferrably. Only when the overlay is closing, its flashes will be rendered into the parent layer (instead of being discarded).

Rendering flash messages

To render a flash message, include an [up-flashes] element in your response. The element's content should be the messages you want to render:

<div up-flashes>
  <strong>User was updated!</strong> <!-- mark-line -->
</div>

<main>
  Main response content ...
</main>

Flashes are targeted automatically

The flashes will always be updated, even if they aren't targeted directly. In the example above, rendering main would also update the [up-flashes] element.

Flashes from closing overlays are shown on a parent layer

Sometimes a fragment update will cause an overlay to close, e.g. when a close condition is reached. In that case no new elements will be rendered into the closing overlay. Any confirmation flashes from the final overlay interaction would be lost.

The [up-flashes] element addresses this by picking up flashes from a closing overlay and rendering them into the parent layer.

Clearing flashes

By default flash messages are kept until they are replaced by new messages.

An empty [up-flashes] element will not clear existing messages. Hence it is safe to always include an empty [up-flashes] element in your application layout to indicate where future flashes should be placed.

Removing messages after a delay

Typically you want to clear flash messages after some time. This compiler removes child elements of your [up-flashes] container after 5 seconds:

up.compiler('[up-flashes] > *', function(message) {
  setTimeout(() => up.destroy(message), 5000)
})

Important

We're only removing the contents of [up-flashes], but not the container itself. The empty flashes container must remain in the layout to indicate where future flashes should be placed.

To animate the removal, pass an { animation } option to up.destroy().

Building a custom flashes container

If you cannot work with the behavior of [up-flashes], consider building your own custom flashes container.

You can use the implementation of [up-flashes] as a template, which looks like this:

<div
  id="flashes"
  role="alert"
  up-hungry
  up-if-layer="subtree"
  up-keep
  up-on-keep="if (!up.element.isEmpty(event.newFragment)) event.preventDefault()"
>
</div>