# Notification components

> **Info:** This is release candidate documentation for **Stream Chat React Native SDK v10**. For the latest stable version, see the [latest version (v9)](https://getstream.io/chat/docs/sdk/react-native/).

The components that render one notification, and the provider that makes a part of the app a notification target. `NotificationList` renders `Notification` for the notification it shows: see [NotificationList](https://getstream.io/chat/docs/sdk/react-native/v10/component-reference/notifications/notification-list/). Every component on this page is exported from `stream-chat-react-native` and `stream-chat-expo`.

## Best practices

- Replace `Notification` through its override key, and render the default inside your component to keep its text, actions and close button. Replacing `NotificationIcon` changes only the icon.
- Choose a notification's text by its `type`, never by `notification.message`. For a type `stream-chat` publishes, the message is untranslated English.
- Call `onDismiss` from your own close button. `NotificationList` passes one that removes the notification and clears its timer.
- Give every part of your app that should show notifications of its own a `NotificationTargetProvider` with a `hostId` that tells it apart.

## Available components

| Component                    | What it is                                                      | Override key       |
| ---------------------------- | --------------------------------------------------------------- | ------------------ |
| `Notification`               | One notification: an icon, the text, actions and a close button | `Notification`     |
| `NotificationIcon`           | The icon of a notification, from its severity                   | `NotificationIcon` |
| `NotificationTargetProvider` | Makes its children a notification target                        | None               |

## Notification

`Notification` renders, in a rounded box on `semantics.backgroundCoreInverse`:

- **the icon**, the `Icon` prop or the `NotificationIcon` key. When the default icon has none for the severity, the text moves into its place;
- **the text**, chosen by the notification's `type`. A type `stream-chat` publishes, and a few the SDK publishes, render a translation key through `t()`; any other type renders `notification.message` as it is. [Translating notifications](https://getstream.io/chat/docs/sdk/react-native/v10/ui/customizing/displaying-notifications/#translating-notifications) lists them;
- **a button for each of `notification.actions`**, with the action's `label`, which calls its `handler`;
- **a close button**, when `showClose` is `true` or the notification has no `duration`. It calls `onDismiss`, or, without one, removes the notification from the store.

On Android, TalkBack announces it through a live region, assertively with the `alert` role for an `error` and politely otherwise. `accessibilityLiveRegion` is Android only, so VoiceOver on iOS doesn't announce it.

| Prop              | Type                                         | Default                    | Description                                                                                       |
| ----------------- | -------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------- |
| `notification`    | `Notification`                               | required                   | The notification, of type `Notification` from `stream-chat`.                                      |
| `onDismiss`       | `() => void`                                 |                            | Called by the close button in place of removing the notification.                                 |
| `showClose`       | `boolean`                                    | `false`                    | Shows the close button on a notification with a `duration`. One without a duration always has it. |
| `Icon`            | `React.ComponentType<NotificationIconProps>` | the `NotificationIcon` key | The icon. A component you pass here always renders, whatever the severity.                        |
| `entryDirection`  | `NotificationEntryDirection`                 |                            | The side the list animated the notification in from. The default doesn't read it.                 |
| `transitionState` | `NotificationTransitionState`                |                            | `'enter'` or `'exit'`, for an animated notification of your own. The SDK doesn't pass it.         |

`NotificationEntryDirection` is `'bottom' | 'left' | 'right' | 'top'`.

## NotificationIcon

`NotificationIcon` picks an icon of `ComponentsContext` from `getNotificationVariant(notification)`, which is the notification's `severity`, or `'default'` without one:

| Variant   | Icon                |
| --------- | ------------------- |
| `error`   | `ExclamationCircle` |
| `warning` | `ExclamationCircle` |
| `success` | `Check`             |
| `loading` | `Reload`            |
| `info`    | none                |
| `default` | none                |

The icon is 20 points, in `semantics.textOnInverse`. For the variants without an icon, `NotificationIcon` renders nothing.

| Prop           | Type           | Default  | Description       |
| -------------- | -------------- | -------- | ----------------- |
| `notification` | `Notification` | required | The notification. |

## NotificationTargetProvider

`NotificationTargetProvider` gives its children a notification target, `{ panel, hostId }`:

- a `NotificationList` inside it with no `panel` and `hostId` shows the notifications of this target;
- `addNotification` from `useNotificationApi()` inside it tags a notification for this target.

The SDK renders one in `Channel`, `Thread`, `ChannelList`, `ThreadList` and channel details, with the panels `channel`, `thread`, `channel-list`, `thread-list` and `channel-details`. A provider inside another replaces its target for its children.

| Prop       | Type                      | Default  | Description                                                                            |
| ---------- | ------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `panel`    | `NotificationTargetPanel` | required | The kind of surface. One of the SDK's panels, or any string of your own.               |
| `hostId`   | `string`                  | required | Which surface of that kind, such as `getChannelNotificationHostId(cid)` for a channel. |
| `children` | `ReactNode`               |          | The part of the app that is the target.                                                |

`useNotificationTargetContext()` returns the nearest provider's target, or `undefined` outside every provider, and never throws.

### Target helpers

| Export                                             | What it does                                                                                                       |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `getChannelNotificationHostId(cid)`                | Returns `channel:<cid>`, the default host of a `Channel`.                                                          |
| `getThreadNotificationHostId(threadId)`            | Returns `thread:<threadId>`, the default host of a `Thread`.                                                       |
| `getNotificationTargetTag(panel, hostId?)`         | Returns the tag `target:<panel>:<hostId>`, or `target:<panel>` for every host of the panel.                        |
| `getNotificationTarget(notification)`              | Returns the target a notification is tagged for, or the channel or thread of the composer in its `origin.context`. |
| `isNotificationForTarget(notification, target)`    | Whether a list for `target` would show the notification.                                                           |
| `isBuiltInNotificationTargetPanel(panel)`          | Whether `panel` is one of the SDK's five panels.                                                                   |
| `excludeCanceledUploadNotifications(notification)` | A list `filter` that hides the upload failures caused by removing an attachment while it uploads.                  |

## Theming

The theme's `notification` key styles the default components: `container`, `contentContainer`, `message`, `iconContainer`, `actionsContainer`, `actionButton` and `closeButton`. The theme also has `notification.actionButtonText`, which nothing reads; an action's text takes the button's color. See [Theme object](https://getstream.io/chat/docs/sdk/react-native/v10/reference/theme/theme-object/#notification).

## Example

A notification with a colored bar for its severity, an icon of your own for `success`, and the default for the rest:

```tsx title="src/notificationOverrides.tsx"
import { View } from "react-native";
import {
  Notification,
  NotificationIcon,
  useComponentsContext,
} from "stream-chat-react-native";
import type {
  ComponentOverrides,
  NotificationIconProps,
  NotificationProps,
} from "stream-chat-react-native";

const severityColors: Record<string, string> = {
  error: "#d32f2f",
  success: "#2e7d32",
  warning: "#ed6c02",
};

const AppNotificationIcon = (props: NotificationIconProps) => {
  const { icons } = useComponentsContext();
  if (props.notification.severity === "success") {
    return <icons.Checkmark height={20} stroke="#ffffff" width={20} />;
  }
  return <NotificationIcon {...props} />;
};

const AppNotification = (props: NotificationProps) => {
  const color = severityColors[props.notification.severity ?? ""];
  return (
    <View
      style={{
        borderLeftColor: color,
        borderLeftWidth: color ? 4 : 0,
        borderRadius: 24,
      }}
    >
      <Notification {...props} />
    </View>
  );
};

// Declared outside the component, so WithComponents gets the same object on every render.
export const notificationOverrides: ComponentOverrides = {
  Notification: AppNotification,
  NotificationIcon: AppNotificationIcon,
};
```

The default `Notification` renders the `NotificationIcon` key, so `AppNotificationIcon` reaches it without being passed as `Icon`.

## Related

- [Displaying notifications](https://getstream.io/chat/docs/sdk/react-native/v10/ui/customizing/displaying-notifications/): targets, routing, translation and what the SDK publishes.
- [Notification hooks](https://getstream.io/chat/docs/sdk/react-native/v10/reference/hooks/notification-hooks/#usenotificationtargetcontext): `useNotificationApi`, `useNotifications` and `useNotificationTargetContext`.
- [Publishing notifications](https://getstream.io/chat/docs/sdk/react-native/v10/state/publishing-notifications/): the store in `stream-chat`, severities, durations and actions.

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react-native/v10/component-reference/notifications/notification-components/](https://getstream.io/chat/docs/sdk/react-native/v10/component-reference/notifications/notification-components/).