Notifications - Enigma docs

Ordering, dedupe by key, sticky errors and dismiss timers that hold rather than run while the tab is hidden. No rendering, no styles.

The queue owns ordering, deduplication, eviction and timers. Rendering is yours - it returns a list and never an opinion about what a toast looks like.

queue behaviour

Nothing queued. Errors stay until dismissed; the rest fade after 5s.

Press "Retry" repeatedly: it replaces in place instead of stacking. Press "Error": it stays while the others fade.

import { useNotifications } from "@enigmax/primitives/react";

const { items, notify, dismiss } = useNotifications();

notify({ title: "Saved", body: "Two files changed", tone: "success" });

import { createNotifications } from "@enigmax/primitives";

const queue = createNotifications({ max: 4, duration: 5000 });

queue.subscribe(items => render(items));
queue.notify({ key: "retry", title: "Retrying", tone: "warning" });

Installation

Adds the package and prints the import to use. This is the way to use them: the package keeps getting fixes, and a dependency is how they reach you.

enigma add notifications

Installs with your project's own package manager - npm, pnpm, yarn or bun - read from its packageManager field or its lockfile.

--copy writes the source into your project instead. Reach for it to EDIT a component, not to use one: a copy is frozen at today's version and stops receiving fixes.

Vanilla

import { createNotifications } from "@enigmax/primitives";

const queue = createNotifications({ max: 4, duration: 5000 });
queue.notify({ key: "sync", title: "Retrying", tone: "warning" });

React

import { useNotifications } from "@enigmax/primitives/react";

const { items, notify, dismiss, pause, resume } = useNotifications();

Bind pause / resume to the stack’s pointer enter and leave, and nothing dismisses itself while a visitor is reading it.

The behaviour worth not rewriting

A repeated key replaces in place, so a retry loop does not build a wall of identical messages.
Errors stay until dismissed by default; everything else self-dismisses. Configurable through stickyTones.
Over max, the oldest dismissable notification makes room. A sticky error is never silently evicted - the one message the visitor most needs is the one a naive queue drops.
pause() holds the remaining time rather than running it, and a hidden tab pauses automatically. A timer that keeps counting in the background fires the moment the visitor comes back, and they never see the message.

Notification shape

Field	Meaning
`key`	Optional. Reuses the slot of a live notification with the same key.
`title` / `body`	The text. `body` is optional.
`tone`	`info`, `success`, `warning`, `error`.
`duration`	ms before self-dismissal. `Infinity` keeps it until dismissed.
`data`	Anything the renderer needs: an action label, an href, an icon name.