Skip to content

Notification Region

A fixed, stacking landmark that renders a notifier’s queue of Notifications.

Pick the placement by attention, not by habit: central placements (bottom-center, top-center) for outcomes of the user’s own actions; peripheral corners (top-end, bottom-end) only for background information — they are exactly where the user may not be looking.

<script>
import NotificationRegion from "@invisible-ui/svelte/NotificationRegion.svelte";
import { createNotifier } from "@invisible-ui/svelte";
</script>

In Elements, the region element owns the queue: there is no separate notifier. show() and the status shorthands return the id that update() and dismiss() take, and the element sends a bubbling dismiss event with detail.id and detail.reason:

<ds-notification-region placement="bottom-center"></ds-notification-region>
<script type="module">
const region = document.querySelector("ds-notification-region");
const id = region.info("Saving…", { closable: false });
region.update(id, { status: "success", title: "Saved", closable: true, duration: 5000 });
</script>

In Elements, Svelte, Vue and React, the region holds new notifications while any modal dialog is open in the document, including a native <dialog> opened with showModal() (ADR 0016). They are neither shown nor announced until the last modal closes; then they appear in order and their auto-dismiss countdowns start. Notifications already on screen when a modal opens stay, with their countdowns held, and a change to one of them shows after the modal closes. The region always mounts in <body>, even when it sits inside a dialog. In Svelte, Vue and React, the notifier’s list still holds the waiting notifications.

A message about the dialog’s own task belongs in the dialog: call notify() on the dialog (the element, the Svelte instance, the Vue template ref or the React handle) to show it in the dialog’s status area. A message that needs a decision now opens a dialog on top.

<script lang="ts">
import { createNotifier } from "@invisible-ui/svelte";
import Dialog from "@invisible-ui/svelte/Dialog.svelte";
import NotificationRegion from "@invisible-ui/svelte/NotificationRegion.svelte";
const notifier = createNotifier();
let dialog: ReturnType<typeof Dialog> | undefined = $state();
// Unrelated to the dialog: the region shows it after the dialog closes.
const onReportReady = () => notifier.info("Report ready", { duration: 6000 });
// About the dialog's task: shown in its status area right away.
const onUploadError = () => dialog?.notify({ status: "danger", title: "Upload failed" });
</script>
<Dialog bind:this={dialog} title="Upload files">…</Dialog>
<NotificationRegion {notifier} />
PropTypeDefaultDescription
notifier *Notifier—
placement"top-start" | "top-center" | "top-end" | "bottom-start" | "bottom-center" | "bottom-end""top-end"
labelstring | undefinedundefinedAccessible name for the region landmark. Defaults to the i18n catalog's "Notices".
maxVisiblenumber0Maximum notices rendered at once. 0 means no limit.
insetstring"1rem"Distance from the viewport edges, as a CSS length. Default 1rem.
swipeablebooleantrueAllow swiping a notification away (pointer/touch). Default true.
durationnumber200Enter/leave/reflow duration in ms.
exitDurationnumber | undefinedundefinedLeave duration in ms. Defaults to 1.75× duration — a gentler exit.
easing(t: number) => numbercubicOutEasing for enter/reflow. Ease-out by default.
exitEasing(t: number) => numbercubicInEasing for the leave animation. Ease-in by default: starts slow and accelerates away, so a dismissal never snaps.
  • Swipe to dismiss (swipeable, on by default): drag a notification horizontally past a short threshold — or flick it — to dismiss; a smaller drag snaps back. It is a pointer enhancement, so the close button and auto-dismiss stay the accessible paths (keyboard and assistive tech are never left without a way out). Vertical scroll is preserved.
  • Hovering or focusing anywhere in the stack pauses every countdown (not only the notification under the pointer), so a burst can be read and acted on without any of them expiring (WCAG 2.2.1).
  • An accessible landmark: role="region" with a label; each Notification inside is its own live region. Mounting more than one region on a page means giving each its own label: two landmarks with the same name are the same entry twice in the landmark list.
  • Notifications enter/leave with a fly/fade transition and the stack reflows via FLIP, disabled under reduced motion.
<script>
const notifier = createNotifier();
</script>
<NotificationRegion {notifier} placement="bottom-center" />
<Button onpress={() => notifier.show({ status: "success", title: "Saved" })}>
Save
</Button>

In React, create the notifier once, outside the component tree, and pass it to the region. The region renders in the browser only, through a portal into <body>. Read the list with useSyncExternalStore(notifier.subscribe, notifier.getSnapshot) when a component needs it.

import { Button, createNotifier, NotificationRegion } from "@invisible-ui/react";
const notifier = createNotifier();
export function App() {
return (
<>
<NotificationRegion notifier={notifier} placement="bottom-center" />
<Button onPress={() => notifier.success("Saved")}>Save</Button>
</>
);
}

Themeable via --ds-notice-* and --ds-elevation-overlay.