Notification
A floating message — the pattern also known as toast or snackbar (names
that describe motion and look; the job is: notify). It is a live region, not a
dialog: it must never interrupt, never steal focus. Stack it inside a
Notification Region
via createNotifier(); for the same message fixed in the page flow, use
Inline Notification.
While a modal dialog is open, the page — notification regions included — is inert: a notification raised then renders underneath the dialog and is not announced. By design: background information waits; feedback about the task in progress belongs inside the dialog, as an Inline Notification (see the dialog overview).
Messages while a dialog is open
Section titled “Messages while a dialog is open”A notification is the wrong place for a message while a modal dialog is open
(ADR 0016).
A message about the dialog’s task goes in the dialog: beside the control that
caused it, or in the dialog’s status area (notify() on the dialog element,
the Svelte instance, the Vue template ref or the React handle). An unrelated
message waits: in the custom elements, Svelte, Vue and React, the
Notification Region
holds it until the dialog closes. A message that needs a decision now opens a
dialog on top.
Auto-dismiss is opt-in
Section titled “Auto-dismiss is opt-in”Notifications are persistent by default (duration = 0): the user reads
and closes them at their own pace. Opt into auto-dismiss (duration in ms)
only for information that requires no reading care and no action. When set,
the countdown pauses on hover and focus (WCAG 2.2.1 Timing).
Position follows attention
Section titled “Position follows attention”- Central positions (
bottom-center,top-center) for messages about what the user was actively doing — outcomes, confirmations, undo. The snack in the demo: high contrast (inverted), bottom-center, persistent. - Peripheral positions (
top-end,bottom-endin LTR) only for background information the user was not involved in — incoming messages, finished background jobs. Peripheral is precisely what the user may not see: never put must-read messages there.
Import
Section titled “Import”<script> import Notification from "@invisible-ui/svelte/Notification.svelte";</script><script setup> import { Notification } from "@invisible-ui/vue";</script>import { Notification } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-notification></ds-notification>In Elements, a <ds-notification-region> usually creates the notifications.
On its own, the element takes its content as attributes and its actions as a
property. It sends a bubbling close event with detail.reason and then
removes itself, unless the event is canceled:
<ds-notification title="Draft deleted" status="neutral" duration="6000"></ds-notification>
<script type="module"> const notification = document.querySelector("ds-notification"); notification.actions = [{ label: "Undo", onClick: () => restoreDraft() }];</script>| Prop | Type | Default | Description |
|---|---|---|---|
status | NotificationStatus | "info" | Feedback status: info | success | warning | danger | neutral. |
title | string | undefined | undefined | |
text | string | undefined | undefined | |
duration | number | 0 | Auto-dismiss delay in ms — opt-in. 0 (default) keeps it until closed. |
closable | boolean | true | |
role | "status" | "alert" | "status" | |
actions | NotificationAction[] | undefined | undefined | |
inverted | boolean | false | High-contrast inverse surface for maximum visibility. Recommended for transient info outcomes that auto-dismiss (saved, offline, downtime…). |
snack | boolean | false | Snackbar layout: one compact row (icon + title + inline action), no description. |
component | import("svelte").Component<any> | import("svelte").ComponentType | undefined | undefined | Rich body: a Svelte component rendered instead of text (ignored in snack). |
componentProps | Record<string, unknown> | {} | Props for component. |
iconShape | "rounded" | "round" | "rounded" | Shape of the FeedbackIcon box — "rounded" (default) or a full "round" circle. |
iconBox | "tint" | "transparent" | "solid" | undefined | undefined | FeedbackIcon box override (see InlineNotification): force "tint"/"solid" on a tinted surface. |
onclose | ((reason: NotificationDismissReason) => void) | undefined | undefined | Called when the notification is dismissed (auto, close button, or action). |
paused | boolean | false | Hold the auto-dismiss countdown (the region sets this while the whole stack is hovered or focused, so a burst of toasts pauses together — not just the one under the pointer). |
icon | Snippet | undefined | undefined | Custom glyph, forwarded to the InlineNotification's FeedbackIcon. |
| Prop | Type | Default | Description |
|---|---|---|---|
status | NotificationStatus | "info" | Feedback status: info | success | warning | danger | neutral. |
title | string | undefined | |
text | string | undefined | |
duration | number | 0 | Auto-dismiss delay in ms — opt-in. 0 (default) keeps it until closed. |
closable | boolean | true | |
role | "status" | "alert" | "status" | |
actions | NotificationAction[] | undefined | |
inverted | boolean | false | High-contrast inverse surface for maximum visibility. Recommended for transient info outcomes that auto-dismiss (saved, offline, downtime…). |
snack | boolean | false | Snackbar layout: one compact row (icon + title + inline action), no description. |
component | Component | undefined | Rich body: a Vue component rendered instead of text (ignored in snack). |
componentProps | Record<string, unknown> | () => ({}) | Props for component. |
iconShape | "rounded" | "round" | "rounded" | Shape of the FeedbackIcon box — "rounded" (default) or a full "round" circle. |
iconBox | "tint" | "transparent" | "solid" | undefined | FeedbackIcon box override (see InlineNotification): force "tint"/"solid" on a tinted surface. |
onClose | (reason: NotificationDismissReason) => void | undefined | Called when the notification closes, with the reason (timeout / user / action). |
paused | boolean | false | Hold the auto-dismiss countdown (the region sets this while the whole stack is hovered or focused, so a burst of toasts pauses together — not just the one under the pointer). |
Slots: icon.
| Prop | Type | Default | Description |
|---|---|---|---|
status | NotificationStatus | "info" | Feedback status: info | success | warning | danger | neutral. |
title | string | — | |
text | string | — | |
duration | number | 0 | Auto-dismiss delay in ms, opt-in. 0 (default) keeps it until closed. |
closable | boolean | true | |
role | "status" | "alert" | "status" | |
actions | NotificationAction[] | — | |
inverted | boolean | false | A high-contrast surface, for short outcomes that auto-dismiss. |
snack | boolean | false | Snackbar layout: one compact row (icon, title, inline action), no body text. |
component | ComponentType<any> | — | Rich body: a component rendered in place of text (ignored in snack). |
componentProps | Record<string, unknown> | — | Props for component. |
iconShape | "rounded" | "round" | "rounded" | Shape of the icon box: "rounded" (default) or a full "round" circle. |
iconBox | "tint" | "transparent" | "solid" | — | Icon box override (see InlineNotification). |
onClose | (reason: NotificationDismissReason) => void | — | Called when the notification closes, with the reason (timeout, user or action). |
paused | boolean | false | Hold the auto-dismiss countdown. The region sets it while the stack is hovered or focused, so a burst of notifications pauses together. |
icon | ReactNode | — | A custom glyph for the icon. |
| Attribute | Reactive | Description |
|---|---|---|
title | yes | |
text | yes | |
status | yes | |
duration | yes | ms, 0 keeps it until closed |
closable | yes | on by default, "false" removes the close button |
close-label | yes | |
role | yes | |
inverted | yes | |
snack | yes | |
icon-shape | yes | |
icon-box | yes | |
paused | yes |
Reactive attributes re-render the element when they change after the first render.
Properties: actions (action buttons that dismiss after they run unless keepOpen), duration, paused.
Emits: close (detail.reason: user, timeout or action; cancelable, and the element removes itself unless the event is canceled).
Accessibility
Section titled “Accessibility”- It is the live region (
role="status", orrole="alert"for urgent messages) — reusing Inline Notification’s anatomy; additions are announced without moving focus. - The auto-dismiss countdown (when opted in) pauses while the notification is hovered or focused, so actions like Undo remain usable (WCAG 2.2.1).
- Actions inside a notification should also be available elsewhere (Undo via shortcut, the opened item findable): a notification is ephemeral by nature.
The notifier API
Section titled “The notifier API”Drive notifications through createNotifier() + NotificationRegion rather
than rendering Notification directly:
- Status helpers:
notifier.success(title, options?), and the same forinfo/warning/danger/neutral— sugar overshow({ status, title }). - Replace by id: pass an
idtoshow()to update a live notification in place (no new entry):show({ id: "save", title: "Saving…" })thenshow({ id: "save", title: "Saved", status: "success" }). onDismiss(reason): fires once when the notification closes, with the reason —"user"(close button or swipe),"timeout","action"(a dismissing action), or"api"(dismiss()/clear()). This is what makes the canonical delete + Undo flow correct: finalize on any reason except"action".- Rich content: pass a
component(pluscomponentProps) to render arbitrary body content — a file preview, an avatar row — instead oftext.
<script> const notifier = createNotifier();
function deleteFile(file) { remove(file); // optimistic notifier.show({ title: `Deleted “${file}”`, duration: 6000, actions: [{ label: "Undo", onClick: () => restore(file) }], onDismiss: (reason) => { if (reason !== "action") commitDelete(file); // timed out / closed → finalize }, }); }</script>
<NotificationRegion {notifier} placement="bottom-end" />In React, component takes a React component and componentProps its
props; the notifier is the same:
notifier.show({ title: `Deleted “${file}”`, duration: 6000, actions: [{ label: "Undo", onClick: () => restore(file) }], onDismiss: (reason) => { if (reason !== "action") commitDelete(file); },});Accessibility
Section titled “Accessibility”- It is the live region (
role="status", orrole="alert"for urgent messages) — reusing Inline Notification’s anatomy; additions are announced without moving focus. - The auto-dismiss countdown (when opted in) pauses while the notification is hovered or focused, so actions like Undo remain usable (WCAG 2.2.1).
- Actions inside a notification should also be available elsewhere (Undo via shortcut, the opened item findable): a notification is ephemeral by nature.