Message paginator

A MessagePaginator is a message list. Every channel has one in channel.messagePaginator, and every thread has one for its replies in thread.messagePaginator. Inside a thread, read the thread's list, not its channel's. This page lists its API in stream-chat.

A message paginator has everything every paginator has, listed in The base paginator. What only message paginators do, such as intervals, jumping and the unread snapshot, is explained on Message paginators.

Requesting vs. rendering order, jumping, and unread state

A message list keeps its data in five stores, each for one concern, so a subscriber wakes only for the changes it reads:

The SDK creates a list with its channel or thread. Apps don't construct one. The two kinds differ in how they request pages:

requestSort is the order pages are requested in, and itemOrder is the order of items. In both lists, items is oldest first. The Channel component sets a channel's page size to 25 when no page size is registered in client.config. See Loading more.

These properties identify a list:

Reading the message list

state has the base paginator's fields:

Each message is a LocalMessage: its status is "sending", "received" or "failed", and its timestamps are in nanoseconds.

This handler runs whenever the messages on screen or the loading state change:

const { messagePaginator } = channel;

const unsubscribe = messagePaginator.state.subscribeWithSelector(
  ({ hasMoreTail, isLoading, items }) => ({ hasMoreTail, isLoading, items }),
  ({ hasMoreTail, isLoading, items }) => {
    console.log(`${items?.length ?? 0} messages`, { hasMoreTail, isLoading });
  },
);

Two methods look up loaded messages:

Loading more

params is described on The base paginator. MessagePaginator.toTail({ requestOptions: { watch: true } }) on a channel's list also watches the channel with the same request.

MessageList and MessageFlashList call MessagePaginator.toTail() when the user scrolls near the oldest loaded message and MessagePaginator.toHead() near the newest one after a jump. With maxLoadedItems set, they also call MessagePaginator.setPruningSuspended() as the user scrolls near the oldest loaded messages, and lift it when they unmount.

The SDK loads a channel's first page itself: Channel.watch() and channel list pages bring the newest messages. A thread's list starts with the replies its thread came with, or loads them when the thread is opened, as Thread wiring explains. Channel.reload() and Thread.reload() refresh the newest loaded messages in place. A reader on an older interval stays there.

Message lists take these settings from client.config. The messagePaginator key applies to channels and threads, and the messagePaginator inside channel or thread overrides it for one of them:

client.config.set({
  // every message paginator
  messagePaginator: { stateThrottleMs: 300 },
  // channels only
  channel: { messagePaginator: { maxLoadedItems: 500, pageSize: 50 } },
  // threads only
  thread: { messagePaginator: { pageSize: 30 } },
});

Register these before any Channel mounts. Channel sets the page size to 25 only when no page size is registered, and a later change under the channel, messagePaginator or messageOperations key derives the list's configuration again, which replaces the 25.

Throttling and the memory cap explains both.

Jumping to a message

Each resolves to true when it got there and false when it didn't. A failed MessagePaginator.jumpToMessage() or MessagePaginator.jumpToTheLatestMessage() also publishes an error notification through client.notifications. A jump that a later jump or reload overtakes resolves to false without a notification. Its page stays loaded but isn't shown.

options is optional and takes these fields:

After a jump, messageFocusSignal holds { signal }. signal is { messageId, reason, token, createdAt, ttlMs }, or null. The token changes on every jump, so two jumps to the same message give two signals. The signal stays until it's cleared:

With a token, the first two act only while that signal is the current one.

MessageList and MessageFlashList follow the signal: they scroll the message to the middle of the list, highlight it, and call MessagePaginator.scheduleMessageFocusSignalClear() once it's on screen. A message list of your own does the same:

const { messagePaginator } = channel;

const unsubscribe = messagePaginator.messageFocusSignal.subscribeWithSelector(
  ({ signal }) => ({ signal }),
  ({ signal }) => {
    if (!signal) return;
    // Scroll your list to signal.messageId, then start the countdown.
    console.log("Scroll to", signal.messageId);
    messagePaginator.scheduleMessageFocusSignalClear({ token: signal.token });
  },
);

await messagePaginator.jumpToMessage(messageId);

Unread state

unreadStateSnapshot keeps a copy of the user's unread state, taken when the list loads its first page. Marking the channel read doesn't change it, so the UI can still show where the user left off.

The channel also changes the snapshot: a new message that counts as unread raises unreadCount, notification.mark_unread sets every field, and truncating the channel clears it. Channel calls MessagePaginator.seedUnreadSnapshot() each time it mounts, so a channel opened again shows the unread state of that moment.

MessagePaginator.jumpToTheFirstUnreadMessage() goes to firstUnreadMessageId when there is one. Otherwise it goes to the first message after lastReadAt, loading a page around that time if needed, and as a last resort to lastReadMessageId. It reads the snapshot first and the user's entry in channel.state.read second. With unreadReferencePolicy: "read-state-only", it reads only channel.state.read. Channel calls it on mount when initialScrollToFirstUnreadMessage is set and the channel has unread messages, and the unread banner of the message list calls it when tapped.

MessagePaginator.seedUnreadSnapshot() and MessagePaginator.jumpToTheFirstUnreadMessage() read the channel's read state in a thread's list too, not the thread's.

liveViewState holds { isViewingLive }, false until something sets it. While it's true on a channel's list, a new message in the channel doesn't count as unread for the user. MessageList and MessageFlashList set it to true while the app is in the foreground and the newest message is on screen, and back to false when they unmount.

Live view and unread explains both.

The latest message

items holds only the interval on screen. After a jump to an old message, the newest message is in another interval, and a new message from someone else goes there too, so items doesn't change. A message the user sends switches the paginator to the newest interval, so they see what they sent.

aggregateState holds the newest message of the channel or thread instead, with these fields:

latestMessage updates when a newer message arrives, when that message is edited, reacted to or deleted, and when it's removed, in which case it falls back to the next newest one. For a channel, thread-only replies don't count, and neither do system messages when the channel type skips them for last_message_at.

Two getters return them at the moment you read them, and don't tell you when they change:

• latestMessage reads aggregateState.latestMessage.
• latestMessageAt is the later of latestMessage.created_at and queriedLatestMessageAt, or null. It can be later than latestMessage when the server has newer messages the client doesn't hold. Channel lists sort by it for last_message_at.

aggregateState is a store of its own, so it publishes only when the newest message changes, not on every page or scroll. The channel list preview reads latestMessage there.

Thread wiring and minimal initialization

A thread's replies are a MessagePaginator with the thread's parent message id. It requests pages from client.getReplies(), newest page first, 50 replies a page, and keeps items oldest first.

Get a thread from client.threads.ensure(), not with new Thread(). A thread created that way knows only its parent message, and its reply list is ready at once:

const thread = client.threads.ensure({ channel, parentMessage: message });

// The reply list and the composer work before anything is loaded.
// For a new thread, items is undefined until its replies load.
console.log(thread.messagePaginator.items);

How the first replies arrive depends on where the thread came from:

• A thread from the thread list or client.getThreadAndHydrate() comes with its latest replies, and its list starts with them.
• A thread from client.threads.ensure() has no replies yet. When its parent message has replies, or its channel isn't watched, it's stale. It loads when it's activated, while client.threads handles events: Thread.reload() fetches the thread and fills the list.

The Thread component also calls MessagePaginator.toTail() when the list has no replies and nothing is loading, so a thread that isn't stale loads its first page too.

Thread.reload() keeps replies that failed to send. Thread and thread manager lists the thread's API.

With offline support

With offline support, the local database changes how a channel's list fills:

• A channel list loaded from the database places each channel's stored newest messages in its message list, unless the channel is active, so a channel opens on them before the server answers. Replies that are only in their thread aren't stored.
• Channel.reload() also keeps the messages that failed to send and are kept in the database.
• When a reload finds that loaded messages were hard-deleted on the server, it removes them from the database too.

See also

• Message paginators explains intervals, jumping, unread tracking and throttling.
• Channel manager and ChannelPaginator lists what every list has.
• Pinned messages paginator lists the API of a channel's pinned messages.
• Message operations explains how sending, editing and deleting change the list.