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

MethodTypeDescription
addNotification(payload: AddNotificationPayload, options?: AddNotificationOptions) => voidEmit a snackbar notification. Auto-tags with the nearest notification target unless targetPanels or target overrides.
addSystemNotification(payload: AddNotificationPayload, options?: AddSystemNotificationOptions) => stringEmit a notification that is excluded from snackbars (tagged system). Returns the notification id.
removeNotification(id: string) => voidRemove a notification from the store by id.
removeNotificationsForCurrentPanel() => voidRemove 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) => voidStart (or restart) the auto-dismiss timer for a notification. NotificationList calls this for the active notification.

AddNotificationPayload

The payload shape comes from stream-chat:

FieldTypeDescription
message (required)stringThe 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.
optionsNotificationOptionsExtra options. See below.

NotificationOptions

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

AddNotificationOptions

FieldTypeDescription
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.
targetPanelsNotificationTargetPanel[]Route this notification to one or more panels. Overrides the inferred target.

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

Previous
NotificationTargetContext
Next
useNotifications