Notification components

The components that render one notification, the provider that makes a part of the app a notification target, and the announcer that reads connection changes to screen readers. 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

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.

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:

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

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.

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

Target helpers

NotificationAnnouncer

NotificationAnnouncer renders nothing. Channel and Thread each render one. It announces to screen readers when the connection goes down, "Offline" or "Reconnecting", and when it comes back, "Connected", and only while enabled and announceConnectionState of the accessibility settings are on. It takes no props and has no override key, and it doesn't read the notifications in client.notifications. Connection announcements explains when it speaks, and Notifications accessibility what reads a notification.

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:

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