Skip to content
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 39 additions & 7 deletions docs/ux/messages-and-notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,15 +60,47 @@ disappears.

## Notifications

> [!NOTE]
> Toast Notifications are not yet available. The NotificationsManager component
> required to display them is not yet implemented. Use Messages in the meantime.

Notifications are transient, dynamic messages that appear independently of the
page layout — typically as "toasts" in a fixed position on screen. Unlike
Messages, they are not tied to a specific location in the UI and dismiss
automatically or on user interaction.

Notifications are suited for communicating events that occur asynchronously or
outside the user's current focus — for example, the result of a background
operation.
Use Notifications to:

- Confirm the result of a background or asynchronous operation
- Communicate events that occur outside the user's current focus
- Provide low-interruption feedback that does not require user action

Do not use Notifications for persistent errors or warnings that require user
attention or action. Use a [Message](#messages) placed close to the relevant
content instead.

### Toast and NotificationManager

Juno provides two components for notifications:

**`NotificationManager`** handles all notification lifecycle — timers,
auto-dismiss, queuing, and screen position. Place it once near the root of your
application.

Comment thread
franzheidl marked this conversation as resolved.
**`Toast`** is the presentational component rendered by `NotificationManager`.
Do not use `Toast` directly — trigger notifications via the `toast()` API
instead.

Notifications use the same semantic variants as Messages: `info`, `success`,
`warning`, `error`, and `danger`.

### Auto-Dismiss

Notifications auto-dismiss after a default timeout. Do not rely on auto-dismiss
alone for `error` or `warning` notifications that require user action — these should stay until acknowledged or actively dismissed. For these cases, a [Message](#messages) may be the better choice.
Comment thread
franzheidl marked this conversation as resolved.

### Dismissible

By default, notifications include a close button. Dismissibility can be
configured globally on `NotificationManager` or overridden per notification.

### Multiple Notifications

`NotificationManager` supports displaying multiple notifications simultaneously.
Additional notifications queue and appear as others close.
Loading