useNotificationApi

useNotificationApi returns helpers for emitting, dismissing, and routing notifications. It wraps the underlying stream-chat NotificationManager and adds React-context-aware target inference, panel-scoped cleanup, and incident-based type generation.

Usage

import { useNotificationApi } from "stream-chat-react-native";

const {
  addNotification,
  addSystemNotification,
  removeNotification,
  removeNotificationsForCurrentPanel,
  runWithNotificationTarget,
  startNotificationTimeout,
} = useNotificationApi();

addNotification(
  {
    message: "Message deleted",
    origin: { emitter: "MessageActions" },
    options: { severity: "success" },
  },
  { incident: { domain: "api", entity: "message", operation: "delete" } },
);

Returns

Method	Type	Description
`addNotification`	`(payload: AddNotificationPayload, options?: AddNotificationOptions) => void`	Emit a snackbar notification. Auto-tags with the nearest notification target unless `targetPanels` or `target` overrides.
`addSystemNotification`	`(payload: AddNotificationPayload, options?: AddSystemNotificationOptions) => string`	Emit a notification that is excluded from snackbars (tagged `system`). Returns the notification id.
`removeNotification`	`(id: string) => void`	Remove a notification from the store by id.
`removeNotificationsForCurrentPanel`	`() => void`	Remove every non-system notification routed to the nearest notification target. `NotificationList` calls this when it unmounts.
`runWithNotificationTarget`	`<T>(callback: () => T \| Promise<T>, target?: NotificationTarget) => Promise<T>`	Run a callback with an "action target" registered so notifications emitted inside it route to a specific target.
`startNotificationTimeout`	`(id: string, durationOverride?: number) => void`	Start (or restart) the auto-dismiss timer for a notification. `NotificationList` calls this for the active notification.

`AddNotificationPayload`

The payload shape comes from stream-chat:

Field	Type	Description
`message` (required)	`string`	The text shown in the snackbar.
`origin` (required)	`{ emitter: string; context?: Record<string, unknown> }`	Source of the notification. `emitter` is required and used to identify the component or feature.
`options`	`NotificationOptions`	Extra options. See below.

`NotificationOptions`

Field	Type	Description
`actions`	`Array<{ label: string; handler: () => void; metadata?: Record<string, unknown> }>`	Action buttons. When present, the dismiss timer is extended to at least 5 seconds.
`duration`	`number`	Auto-dismiss duration in milliseconds. `0` means persistent, so the notification stays until dismissed manually. Notifications without a resolved duration are persistent too.
`metadata`	`Record<string, unknown>`	Free-form data attached to the notification (e.g. `dedupeKey`, `reason`, `entryDirection`).
`originalError`	`Error`	The original `Error` for error notifications. Useful for logging and analytics.
`severity`	`'error'` \| `'warning'` \| `'info'` \| `'success'` \| `string`	Visual treatment + accessibility semantics. See the severity model.
`tags`	`string[]`	Additional tags. Target tags (`target:<panel>` / `target:<panel>:<hostId>`) are added automatically.
`type`	`string`	Category string in `domain:entity:operation:status` form. Prefer `incident` to compute it for you.

`AddNotificationOptions`

Field	Type	Description
`incident`	`{ domain: string; entity: string; operation: string; status?: string }`	Builds `type` as `<domain>:<entity>:<operation>:<status>`. `status` defaults to `'failed'` for error severity, `'success'` for success, otherwise the severity value.
`target`	`{ hostId: string; panel: NotificationTargetPanel }`	Route this notification to a specific snackbar host. Overrides the inferred target.
`targetPanels`	`NotificationTargetPanel[]`	Route this notification to one or more panels. Overrides the inferred target.

AddSystemNotificationOptions accepts only incident; system notifications are never routed to a panel.