# Notifications

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

Notifications are the short messages the SDK shows after something happens: "Message pinned" after a pin, "Error uploading attachment" after a failed upload. This page covers what users see and when, and points to the pages that explain each part.

## What users get

The user flags a message in a thread:

1. "Message has been successfully flagged" slides in at the bottom of the thread, with a success icon.
2. Three seconds after it appears, it slides out.
3. A screen reader reads "Success notification: Message has been successfully flagged".

If the flag fails, an error notification appears in the same place: the server's error message, or "Error adding flag" when there is none. A screen reader reads it at once, interrupting what it was saying.

What users see follows a few rules:

- **Where.** A notification appears in the part of the screen where it happened: the channel, the thread, the channel list, the thread list, or an open dialog.
- **One at a time.** Each part of the screen shows one notification and queues the rest. A notification without a duration, such as one with a button the user has to press, jumps the queue.
- **How long.** A notification stays three seconds by default, counted from when it appears. One without a duration stays until the user closes it, and shows a close button.
- **In the user's language.** The text is translated with the rest of the UI.

A lost connection is different. `Chat` publishes "Waiting for network…" or "Reconnecting…", but no part of the screen shows it until the app renders a banner. [Connection status](https://getstream.io/chat/docs/sdk/react/v15/features/app-experience/connection-status/) covers that.

## How it works across the layers

### State: client.notifications

Every notification lives in `client.notifications`, the client's notification manager. It holds the list in `client.notifications.store`, and the default duration for each severity: `error`, `warning`, `info` and `success`.

`stream-chat` publishes there itself when an upload, a send, an edit, a poll vote or a jump to a message goes wrong. Each notification has a `type`, such as `api:attachment:upload:failed`, that says what it's about. [Publishing notifications](https://getstream.io/chat/docs/sdk/react/v15/state/publishing-notifications/) explains the manager, the types and the full list of what `stream-chat` publishes.

### UI: lists, the notification and the announcer

- **Publishing.** The React components publish with `useNotificationApi()`: message actions, channel-list row actions, channel details, polls, location sharing, reactions and audio. The hook tags each notification for the part of the screen the component sits in, called its panel.
- **Showing.** A `NotificationList` serves each panel: the message list of a channel or a thread, `ChannelNavigation`, `ThreadList` and each open modal. A list shows the notifications tagged for its panel, one at a time, and starts each one's countdown when it appears.
- **Rendering one.** `Notification` renders a notification: its icon, its translated text, its action buttons and a close button.
- **Announcing.** `Chat` renders a `NotificationAnnouncer`, which reads every new notification to screen readers, whether or not a list shows it.

A notification tagged `system`, such as the lost-connection one, is shown by no list. The app renders it with `useSystemNotifications()`.

[Displaying notifications](https://getstream.io/chat/docs/sdk/react/v15/ui/customizing/displaying-notifications/) explains the panels and how notifications reach them, the queue, translation, system notifications, and what each React component publishes.

### Layout

The layout decides nothing about notifications. A notification follows the component that published it: a flag inside a `Thread` goes to that thread's list, wherever the layout puts the thread.

## Turning it on or off

Notifications are always on, and nothing in `client.config` or the dashboard turns them off. What a user can trigger depends on their capabilities: a user who can't flag messages has no Flag action, so never sees "Message has been successfully flagged".

To show none, pass `Chat` a display filter that rejects every notification. The announcer reads notifications whether a list shows them or not, so replace it too:

```tsx
import type { PropsWithChildren } from "react";
import { Chat, WithComponents } from "stream-chat-react";
import type { NotificationDisplayFilter } from "stream-chat-react";

// No list shows a notification.
const hideAllNotifications: NotificationDisplayFilter = () => false;

// Screen readers hear none either.
const SilentAnnouncer = () => null;
const overrides = { NotificationAnnouncer: SilentAnnouncer };

export const App = ({ children }: PropsWithChildren) => (
  <WithComponents overrides={overrides}>
    <Chat client={client} notificationDisplayFilter={hideAllNotifications}>
      {children}
    </Chat>
  </WithComponents>
);
```

`WithComponents` wraps `Chat` here because `Chat` reads the announcer from the components above it.

## Customizing

### Publishing your own

Call `addNotification` from `useNotificationApi()` in a component inside `Chat`. The notification goes to the panel the component sits in:

```tsx
import { useNotificationApi } from "stream-chat-react";

export const CopyLinkButton = ({ link }: { link: string }) => {
  const { addNotification } = useNotificationApi();

  const copy = async () => {
    await navigator.clipboard.writeText(link);
    addNotification({
      emitter: "CopyLinkButton",
      message: "Link copied",
      severity: "success",
      type: "app:link:copy:success",
    });
  };

  return (
    <button onClick={copy} type="button">
      Copy link
    </button>
  );
};
```

[Routing notifications](https://getstream.io/chat/docs/sdk/react/v15/ui/customizing/displaying-notifications/#routing-notifications) shows how to send it to another panel. Outside React, publish with `client.notifications.add()`, as in [Publishing a notification](https://getstream.io/chat/docs/sdk/react/v15/state/publishing-notifications/#publishing-a-notification).

### How long notifications stay

The durations are client settings, set per severity. Naming one keeps the others at three seconds:

```ts
client.config.set({
  client: { notifications: { durations: { error: 8000 } } },
});
```

[Configuration](https://getstream.io/chat/docs/sdk/react/v15/state/state-and-entities/configuration/) explains `client.config`, and [Severity, actions and durations](https://getstream.io/chat/docs/sdk/react/v15/state/publishing-notifications/#severity-actions-and-durations) covers durations for one notification and notifications that stay.

### Where and how they look

- Move the lists to the top, or change which queued notification shows next: [Replacing the list or a notification](https://getstream.io/chat/docs/sdk/react/v15/ui/customizing/displaying-notifications/#replacing-the-list-or-a-notification).
- Change colors and shapes with CSS: [Styling](https://getstream.io/chat/docs/sdk/react/v15/ui/customizing/displaying-notifications/#styling).
- Keep some notifications out of some panels: [Display filter](https://getstream.io/chat/docs/sdk/react/v15/ui/customizing/displaying-notifications/#display-filter).

### What they say

The text of a built-in notification comes from a translation key. Override the key, or register a translator for the notification's type: [Translating notifications](https://getstream.io/chat/docs/sdk/react/v15/ui/customizing/displaying-notifications/#translating-notifications).

### What screen readers hear

Replace `NotificationAnnouncer` to skip some notifications or reword them: [Customizing notification announcements](https://getstream.io/chat/docs/sdk/react/v15/features/app-experience/accessibility/#customizing-notification-announcements).

### A banner for system notifications

Render the lost-connection notification, and system notifications of your own, as a banner: [Connection status](https://getstream.io/chat/docs/sdk/react/v15/features/app-experience/connection-status/) and the [System notification banner](https://getstream.io/chat/docs/sdk/react/v15/recipes/app/system-notification-banner/) recipe.

## Reference

- [Publishing notifications](https://getstream.io/chat/docs/sdk/react/v15/state/publishing-notifications/): `client.notifications`, the notification types and what `stream-chat` publishes.
- [Displaying notifications](https://getstream.io/chat/docs/sdk/react/v15/ui/customizing/displaying-notifications/): the `NotificationList` and `Notification` props, and what the React components publish.
- [Notification hooks](https://getstream.io/chat/docs/sdk/react/v15/reference/hooks/notification-hooks/): `useNotificationApi`, `useNotifications` and `useSystemNotifications`.
- [Chat](https://getstream.io/chat/docs/sdk/react/v15/component-reference/chat/chat/): the `notificationDisplayFilter` prop.
- [ComponentContext](https://getstream.io/chat/docs/sdk/react/v15/component-reference/channel/componentcontext/): the `Notification`, `NotificationList` and `NotificationAnnouncer` override keys.
- [Configuration tree](https://getstream.io/chat/docs/sdk/react/v15/reference/state/configuration-tree/): `client.notifications.durations`.

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react/v15/features/app-experience/notifications/](https://getstream.io/chat/docs/sdk/react/v15/features/app-experience/notifications/).