Indicators

The SDK's loading, empty-state, pagination and typing indicators. This page lists where each one renders, how to replace it, and its props. The Components pages show them in context: Channel list UI, Message list UI, Thread UI and Channel UI.

Best practices

• Replace an indicator through its override key, with WithComponents. The lists don't take indicators as props.
• The channel list has keys of its own, such as EmptyListIndicator. An EmptyStateIndicator override doesn't reach it.
• Keep a loading or empty state the size of what it stands in for, so the layout doesn't jump when the data arrives.
• Treat TypingIndicator, at the bottom of the message list, and TypingIndicatorHeader, in the header, as two separate parts.
• To change every spinner at once, replace the IconLoading icon: LoadingIndicator renders it.

Available components

Every component here imports from stream-chat-react.

UI customization

EmptyStateIndicator

The message lists render the EmptyStateIndicator override with listType="message" in a channel and listType="thread" in a thread. The default shows "Send a message to start the conversation", or messageText when passed, and nothing in a thread.

The other lists have their own keys:

• the channel list renders EmptyListIndicator, which receives no props and defaults to <EmptyStateIndicator listType="channel" />, "No conversations yet";
• the thread list renders ThreadListEmptyPlaceholder.

LoadingErrorIndicator

LoadingErrorIndicator renders "Error: " and error.message, and nothing without an error. The SDK doesn't render it, and it has no override key. Render it yourself where a load of your own can fail. A failed channel list query is reported as a notification instead: see Channel list UI.

LoadingIndicator

These parts render the LoadingIndicator override: VirtualizedMessageList while it loads a page of messages, MessageList while it loads an older page (its loadingMore prop changes when), the thread list's default ThreadListLoadingIndicator, an attachment preview while the server confirms its upload, and a video attachment while its player loads. The SDK passes it no props that change how it looks.

Other spinners render LoadingIndicator directly, not through the key: the channel list's next page, LoadMoreButton, the unseen threads banner, poll answer and vote lists, the image gallery, and the lists in channel details. All of them, through the key or not, render the IconLoading icon, so replacing that icon changes every spinner. Icons shows how.

LoadMorePaginator and LoadMoreButton

LoadMorePaginator renders its children and, while hasNextPage is true, a LoadMoreButton that calls loadNextPage. Use them for a list of your own. ChannelList has no paginator prop: it loads the next page when it's scrolled to the bottom, and shows LoadingNextPageIndicator meanwhile.

TypingIndicator

MessageList passes the TypingIndicator override isMessageListScrolledToBottom and scrollToBottom. It shows only while the list is scrolled to the latest message, and scrolls the list down when it appears. VirtualizedMessageList has no default: it renders a typing indicator only when the TypingIndicator key is set.

It reads the typing events from the composer that useMessageComposerController() returns, leaves out the current user, and renders nothing when typing events are off for the channel. Typing events reach the channel's composer only, so inside a Thread it shows nothing. Typing indicators covers the feature end to end.

TypingIndicatorHeader

TypingIndicatorHeader replaces the subtitle of ChannelHeader and ThreadHeader while someone is typing. It has no override key: a custom header renders it itself. Without threadList, it shows typing in the channel. With threadList, it looks for typing in the thread of the Thread around it, but like TypingIndicator it reads the thread's composer there, which typing events don't reach, so it shows nothing in ThreadHeader.

EmptyStateIndicatorProps

LoadingErrorIndicatorProps

LoadingIndicatorProps

LoadingIndicatorProps are the props of an SVG element, plus:

It passes them to the IconLoading icon, with the class str-chat__loading-indicator in place of any className you pass.

LoadMoreButtonProps

LoadMorePaginatorProps

LoadMorePaginatorProps also accepts hasPreviousPage, loadPreviousPage, LoadingIndicator and threshold, from the shared PaginatorProps type, but LoadMorePaginator doesn't read them.

TypingIndicatorProps

Whether it shows typing in the channel or in a thread depends on whether it renders inside a Thread, not on a prop.

TypingIndicatorHeaderProps

Examples

Replace the message list's empty state

import { Channel, MessageList, WithComponents } from "stream-chat-react";
import type { EmptyStateIndicatorProps } from "stream-chat-react";

const EmptyChannel = ({ listType }: EmptyStateIndicatorProps) =>
  listType === "message" ? (
    <p className="app-empty-channel">No messages yet. Say hi!</p>
  ) : null;

export const App = () => (
  <WithComponents overrides={{ EmptyStateIndicator: EmptyChannel }}>
    <Channel channel={channel}>
      <MessageList />
    </Channel>
  </WithComponents>
);

Returning null for "thread" keeps a thread's list empty, as the default does.

Replace the channel list's empty state

import { ChannelList, WithComponents } from "stream-chat-react";

const NoChannels = () => (
  <p className="app-no-channels">Join a channel to start.</p>
);

export const Channels = () => (
  <WithComponents overrides={{ EmptyListIndicator: NoChannels }}>
    <ChannelList paginator={paginator} />
  </WithComponents>
);

Show typing in VirtualizedMessageList

import {
  Channel,
  TypingIndicator,
  VirtualizedMessageList,
  WithComponents,
} from "stream-chat-react";

export const App = () => (
  <WithComponents overrides={{ TypingIndicator }}>
    <Channel channel={channel}>
      <VirtualizedMessageList />
    </Channel>
  </WithComponents>
);