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.
Import
Section titled “Import”<script> import NotificationRegion from "@invisible-ui/svelte/NotificationRegion.svelte"; import { createNotifier } from "@invisible-ui/svelte";</script><script setup> import { NotificationRegion, createNotifier } from "@invisible-ui/vue";</script>import { NotificationRegion, createNotifier } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-notification-region></ds-notification-region>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>Messages while a dialog is open
Section titled “Messages while a dialog is open”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} />| Prop | Type | Default | Description |
|---|---|---|---|
notifier * | Notifier | — | |
placement | "top-start" | "top-center" | "top-end" | "bottom-start" | "bottom-center" | "bottom-end" | "top-end" | |
label | string | undefined | undefined | Accessible name for the region landmark. Defaults to the i18n catalog's "Notices". |
maxVisible | number | 0 | Maximum notices rendered at once. 0 means no limit. |
inset | string | "1rem" | Distance from the viewport edges, as a CSS length. Default 1rem. |
swipeable | boolean | true | Allow swiping a notification away (pointer/touch). Default true. |
duration | number | 200 | Enter/leave/reflow duration in ms. |
exitDuration | number | undefined | undefined | Leave duration in ms. Defaults to 1.75× duration — a gentler exit. |
easing | (t: number) => number | cubicOut | Easing for enter/reflow. Ease-out by default. |
exitEasing | (t: number) => number | cubicIn | Easing for the leave animation. Ease-in by default: starts slow and accelerates away, so a dismissal never snaps. |
| Prop | Type | Default | Description |
|---|---|---|---|
notifier * | Notifier | — | The notifier whose queue this region renders. |
placement | NotificationPlacement | "top-end" | |
label | string | undefined | Accessible name for the region landmark. Defaults to the i18n catalog's "Notifications". |
maxVisible | number | 0 | Optional cap on notifications rendered at once. 0 (default) means no count cap — the pile fills the window height and clips the oldest at the far edge. Set a number to also limit by count. |
inset | string | "1rem" | Distance from the viewport edges, as a CSS length. Default 1rem. |
swipeable | boolean | true | Allow swiping a notification away (pointer/touch). Default true. |
duration | number | 200 | Enter/reflow duration in ms. |
exitDuration | number | undefined | Leave duration in ms. Defaults to 1.75× duration — a gentler exit. |
| Prop | Type | Default | Description |
|---|---|---|---|
notifier * | Notifier | — | The notifier whose queue this region renders. |
placement | NotificationPlacement | "top-end" | |
label | string | — | Accessible name for the region landmark. Defaults to the catalog's "Notifications". |
maxVisible | number | 0 | Optional cap on notifications rendered at once. 0 (default) means no count cap: the pile fills the window height and the oldest are clipped at the far edge. |
inset | string | "1rem" | Distance from the viewport edges, as a CSS length. Default 1rem. |
swipeable | boolean | true | Allow swiping a notification away (pointer and touch). Default true. |
duration | number | 200 | Enter and reflow duration in ms. |
exitDuration | number | — | Leave duration in ms. Defaults to 1.75 times duration, a gentler exit. |
| Attribute | Reactive | Description |
|---|---|---|
placement | yes | top-end by default |
label | yes | the landmark name |
max-visible | yes | 0, no count cap |
inset | yes | distance from the viewport edges, 1rem |
swipeable | yes | on by default, "false" turns it off |
duration | yes | enter and reflow ms, 200 |
exit-duration | yes | leave ms, 1.75 times duration |
Reactive attributes re-render the element when they change after the first render.
Properties: notifications (the queue, oldest first, read only, including the notifications waiting for a modal to close).
Methods: show(options) returns the id, info, success, warning, danger and neutral(title, options), update(id, patch), dismiss(id, reason), clear(), promise(promise, messages).
Emits: dismiss (detail.id, detail.reason) after a notification leaves the queue.
Interaction
Section titled “Interaction”- 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).
Accessibility
Section titled “Accessibility”- 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 ownlabel: 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.
Example
Section titled “Example”<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.