Skip to content

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).

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.

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).

  • 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-end in 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.
<script>
import Notification from "@invisible-ui/svelte/Notification.svelte";
</script>

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>
PropTypeDefaultDescription
statusNotificationStatus"info"Feedback status: info | success | warning | danger | neutral.
titlestring | undefinedundefined
textstring | undefinedundefined
durationnumber0Auto-dismiss delay in ms — opt-in. 0 (default) keeps it until closed.
closablebooleantrue
role"status" | "alert""status"
actionsNotificationAction[] | undefinedundefined
invertedbooleanfalseHigh-contrast inverse surface for maximum visibility. Recommended for transient info outcomes that auto-dismiss (saved, offline, downtime…).
snackbooleanfalseSnackbar layout: one compact row (icon + title + inline action), no description.
componentimport("svelte").Component<any> | import("svelte").ComponentType | undefinedundefinedRich body: a Svelte component rendered instead of text (ignored in snack).
componentPropsRecord<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" | undefinedundefinedFeedbackIcon box override (see InlineNotification): force "tint"/"solid" on a tinted surface.
onclose((reason: NotificationDismissReason) => void) | undefinedundefinedCalled when the notification is dismissed (auto, close button, or action).
pausedbooleanfalseHold 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).
iconSnippet | undefinedundefinedCustom glyph, forwarded to the InlineNotification's FeedbackIcon.
  • It is the live region (role="status", or role="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.

Drive notifications through createNotifier() + NotificationRegion rather than rendering Notification directly:

  • Status helpers: notifier.success(title, options?), and the same for info / warning / danger / neutral — sugar over show({ status, title }).
  • Replace by id: pass an id to show() to update a live notification in place (no new entry): show({ id: "save", title: "Saving…" }) then show({ 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 (plus componentProps) to render arbitrary body content — a file preview, an avatar row — instead of text.
<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);
},
});
  • It is the live region (role="status", or role="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.