Channel Read State

This guide intends to provide an overview how channel read state is handled by default in the SDK and how to customize this behavior to our liking.

The model

The React SDK maintains channel read state for UI components inside Channel component in a separate variable channelUnreadUiState. This state is dedicated to show unread count on components UnreadMessagesSeparator and UnreadMessagesNotification (or other custom components that need its behavior). The channelUnreadUiState is special in that when a channel is opened and marked read, the channelUnreadUiState does not reflect this initial update. This is in order the user can see, how many unread messages there have been left since the previous session.

Channel read state reflecting the current back-end state can be accessed via channel.state.read mapping.

Channel UI unread state

The state is maintained by Channel component and shared with its children via ChannelStateContext as channelUnreadUiState. The state format is as follows:

Channel read state for all users

The read state is extracted from the channel query response, specifically from each ChannelResponse object’s read attribute. This is internally transformed from an array of users’ read statuses into and object indexed by user id. The read state is updated upon receiving WS events like message.read, notification.mark_unread, message.new. Each value of the read state object has then the following structure:

Access the read state

In the SDK, the read and channelUnreadUiState can be accessed via useChannelStateContext consumer:

import { useChannelStateContext, useChatContext } from "stream-chat-react";

const Component = (props) => {
  const { client } = useChatContext();
  const { read, channel, channelUnreadUiState } = useChannelStateContext();

  // channel read state for some user
  const channelReadStateForAUser = read[props.user.id];

  // channel read state for own user
  const channelReadStateForMyUser = client.user && read[client.user.id];

  // easier way to access own user's unread count for a given channel
  const unreadCount = channel.unreadCount();

  //... code
};

Mark a channel read

Channel can be marked read using the markRead() function provided via ChannelActionContext:

import { useChannelActionContext } from "stream-chat-react";

const MarkReadButton = (props) => {
  const { markRead } = useChannelActionContext();

  return (
    <button {...props} onClick={() => markRead()}>
      Mark read
    </button>
  );
};

The function accepts a single options parameter of the following format:

Default components involved in handling read state

The default components included in marking a channel read:

The default components included in marking a channel unread:

The default components reflecting channel unread count:

Default channel read state handling

The channel is marked read in the following scenarios:

1. User enters a channel with unread messages if Channel prop markReadOnMount is enabled (default behavior).
2. User scrolls up and back down to the latest message.
3. User clicks the button on the default UnreadMessagesNotification component to mark channel read.

The channel is marked unread in the following scenarios:

1. User with read-events permission selects Mark as unread option from the MessageActionsBox.

The component UnreadMessagesSeparator is shown immediately below the last read message. It can be followed by own message or a message posted by another user. It does not show unread count if:

• showCount prop is enabled and among the unread messages are only own messages (own message can be marked unread).
• showCount prop is disabled (default)

Channel read state handling customization

Customization through component props

There is a possibility to configure when a channel is marked read by tweaking these default components’ props:

Customization through custom components

We can override the following components via Channel’s component context:

Custom UnreadMessagesSeparator component

Will be rendered before the first unread message.

import { Channel, UnreadMessagesSeparatorProps } from "stream-chat-react";

const UnreadMessagesSeparator = (props: UnreadMessagesSeparatorProps) => {
  //... custom implementation
};
const Component = ({ children }) => (
  <Channel UnreadMessagesSeparator={UnreadMessagesSeparator}>
    {children}
  </Channel>
);

The component can be configured through the following props:

import {
  UnreadMessagesSeparator as StreamUnreadMessagesSeparator,
  UnreadMessagesSeparatorProps,
} from "stream-chat-react";

const UnreadMessagesSeparator = (props: UnreadMessagesSeparatorProps) => {
  return <StreamUnreadMessagesSeparator {...props} showCount />;
};

Custom UnreadMessagesNotification component

Will be rendered only when UnreadMessagesSeparator is not visible in message list. The default implementation positions the notification as a floating element above the messages in a message list. It shows the number of unread messages since the user has scrolled away from the latest message (bottom of the message list).

import { Channel, UnreadMessagesNotificationProps } from "stream-chat-react";

const UnreadMessagesNotification = (props: UnreadMessagesNotificationProps) => {
  //... custom implementation
};
const Component = ({ children }) => (
  <Channel UnreadMessagesNotification={UnreadMessagesNotification}>
    {children}
  </Channel>
);

The component can be configured through the following props:

import {
  UnreadMessagesNotification as StreamUnreadMessagesNotification,
  UnreadMessagesNotificationProps,
} from "stream-chat-react";

const UnreadMessagesNotification = (props: UnreadMessagesNotificationProps) => {
  return (
    <StreamUnreadMessagesNotification
      {...props}
      queryMessageLimit={50}
      showCount
    />
  );
};

Custom MessageNotification component

The SDK exports ScrollToBottomButton that shows the unread count since the point the user has scrolled away from the newest messages in the list.

We can implement our own message notification component.

import { MessageNotificationProps, Channel } from "stream-chat-react";

const MessageNotification = (props: MessageNotificationProps) => {
  //... custom implementation
};

const Component = ({ children }) => (
  <Channel MessageNotification={MessageNotification}>{children}</Channel>
);

Jumping to the first unread message

Default SDK component to jump to the first unread message

The SDK provides a component UnreadMessagesNotification, that when clicked on the part Unread messages, the message list scrolls to the first unread message. If the first unread message is not loaded in the local channel state, the message is retrieved from the API.

API to jump to the first unread message

Use jumpToFirstUnreadMessage() function to implement custom UI to jump to the first unread message. The function takes one parameter queryMessageLimit that specifies the message page size if the message has to be loaded from the back-end API.