Notification components

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. 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 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.

Example

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

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.

Displaying notifications: targets, routing, translation and what the SDK publishes.
Notification hooks: useNotificationApi, useNotifications and useNotificationTargetContext.
Publishing notifications: the store in stream-chat, severities, durations and actions.