useNotifications API

Notification lifecycle management with severity levels, state mutations, toast queuing, and auto-dismiss.

Explore these related pages for additional context and usage patterns.

Page	Category
useNotifications	Plugins
Snackbar	Semantic
createRegistry	Registration
createQueue	Registration
createPlugin	Foundation

Functions

createNotifications

(_options?: NotificationsOptions & { adapter?: NotificationsAdapter; }) => NotificationsContext<NotificationTicketInput, NotificationTicket<NotificationTicketInput>>

createNotificationsContext

<_E>(_options?: NotificationsPluginOptions | undefined) => ContextTrinity<_E>

createNotificationsPlugin

(_options?: (NotificationsPluginOptions & Pick<{ namespace?: string; persist?: boolean; devtools?: boolean; }, "devtools">) | undefined) => Plugin

useNotifications

<_E>(namespace?: string) => _E

Options

events

boolean | undefined

Enable event emission for registry operations

Default: false

reactive

boolean | undefined

Enable reactive behavior for registry operations

Default: false

timeout

number | undefined

Default auto-dismiss timeout in ms for the toast queue.

Default: 3000

Properties

collection

ReadonlyMap<ID, E>

The collection of tickets in the registry

size

number

The number of tickets in the registry

queue

QueueContext<QueueTicketInput<unknown>, QueueTicket<QueueTicketInput<unknown>>>

The toast display queue. Access queue.values(), queue.pause(), queue.resume().

adapter

NotificationsAdapter<NotificationTicketInput, NotificationTicket<NotificationTicketInput>> | undefined

Active notifications adapter, when the plugin was installed with one.

Methods

clear

() => void

Clear the entire registry

has

(id: ID) => boolean

Check if a ticket exists by ID

keys

() => readonly ID[]

Get all registered IDs

browse

(value: E["value"]) => readonly ID[] | undefined

Browse for an ID(s) by value

lookup

(index: number) => ID | undefined

Lookup a ticket by index number

get

(id: ID) => E | undefined

Get a ticket by ID

upsert

(id: ID, ticket?: Partial<Z>, event?: string) => E

Update or insert a ticket by ID

values

() => readonly E[]

Get all values of registered tickets

entries

() => readonly [ID, E][]

Get all entries of registered tickets

register

(ticket?: Partial<Z & RegistryTicket>) => E

unregister

(id: ID) => void

Unregister a ticket by ID

reindex

() => void

Reset the index directory and update all tickets

move

(id: ID, toIndex: number) => E | undefined

Move a ticket to a new index position

reorder

(ids: ID[]) => void

Reorder the registry to match a canonical permutation of ids in one pass.

seek

(direction?: "first" | "last", from?: number, predicate?: (ticket) => boolean) => E | undefined

Seek for a ticket based on direction and optional predicate

on

<K extends Extensible<RegistryEventName>>(event: K, cb: RegistryEventCallback<E, K>) => void

Listen for registry events

off

<K extends Extensible<RegistryEventName>>(event: K, cb: RegistryEventCallback<E, K>) => void

Stop listening for registry events

emit

<K extends Extensible<RegistryEventName>>(event: K, data: EventPayload<E, K>) => void

Emit an event with data

dispose

() => void

Clears the registry and removes all listeners

onboard

(registrations: Partial<Z & RegistryTicket>[]) => E[]

Onboard multiple tickets at once

offboard

(ids: ID[]) => Partial<Z>[]

Offboard multiple tickets at once, returning the input shapes that were removed.

batch

<R>(fn: () => R) => R

Execute operations in a batch, deferring event dispatch and the reactive notification until complete

send

(input: Z) => E

Create a notification and enqueue for toast display.

read

(id: ID) => void

Mark as read. Emits notification:read.

unread

(id: ID) => void

Mark as unread. Emits notification:unread.

seen

(id: ID) => void

Mark as seen. Emits notification:seen.

unarchive

(id: ID) => void

Restore from archive. Emits notification:unarchived.

snooze

(id: ID, until: Date) => void

Snooze until the given time. Emits notification:snoozed.

wake

(id: ID) => void

Cancel snooze. Emits notification:unsnoozed.

readAll

() => void

Mark all unread notifications as read.

archiveAll

() => void

Archive all unarchived notifications.