# 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

```tsx
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](/chat/docs/sdk/react-native/guides/in-app-notifications-overview/#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.


---

This page was last updated at 2026-05-14T07:09:00.776Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react-native/ui-components/in-app-notifications/hooks/use-notification-api/](https://getstream.io/chat/docs/sdk/react-native/ui-components/in-app-notifications/hooks/use-notification-api/).