System message

A system message is a message of type system. It reports an event in the channel rather than something a user wrote, for example a member joining or a moderation command. MessageList and VirtualizedMessageList render it with the MessageSystem override instead of the message UI. This recipe replaces it.

Note:

What you'll build

  • A system message on a quiet card
  • The event in emphasis, with who triggered it
  • The time of the event

Preview

A custom system message on a quiet card: the event, the user who triggered it and the time

Approach: Replace one part. Choosing where to start explains the approaches.

Starts from: the base app. The page shows only what the recipe adds.

Best practices

  • Keep system messages visually distinct from user messages, but quieter.
  • Show the message's text: it says what happened.
  • Show who triggered the event only where your app's privacy rules allow it. The sender is message.user.
  • Replace MessageSystem for a different layout. For a different look only, style str-chat__message--system.
  • Test with every event your app turns into a system message, such as members being added and removed, and moderation commands.

Default system message component

The default is <EventComponent/>. It renders the message's text in a centered line. With the list's unsafeHTML prop set, it renders the message's html instead, and falls back to the text when the message has no html:

The default system message

The default system message

A system message comes from the server. Your backend sends one with type: "system", as System messages shows, and adding or removing members can create one, as Channel members shows.

Custom system message component

This component shows the text, the user who triggered the event, and the time, on a quiet card in the middle of the list:

src/CustomSystemMessage.tsx
import type { PropsWithChildren } from "react";
import { convertTimestampToDate } from "stream-chat";
import type { EventComponentProps } from "stream-chat-react";
import { Avatar, WithComponents } from "stream-chat-react";
import "./CustomSystemMessage.css";

const CustomSystemMessage = ({ message }: EventComponentProps) => {
  const { created_at, text, user } = message;
  const date = convertTimestampToDate(created_at);
  const userName = user?.name || user?.id;

  return (
    <div className="cookbook-system-message">
      <div className="cookbook-system-message__text">{text?.trim()}</div>
      <div className="cookbook-system-message__meta">
        {user && (
          <span className="cookbook-system-message__actor">
            <Avatar imageUrl={user.image} size="xs" userName={userName} />
            {userName}
          </span>
        )}
        {date && (
          <time dateTime={date.toISOString()}>
            {date.toLocaleTimeString([], {
              hour: "numeric",
              minute: "2-digit",
            })}
          </time>
        )}
      </div>
    </div>
  );
};

// Declared once, so WithComponents gets the same object on every render.
const overrides = { MessageSystem: CustomSystemMessage };

export const WithCustomSystemMessages = ({ children }: PropsWithChildren) => (
  <WithComponents overrides={overrides}>{children}</WithComponents>
);

The rules sit in the stream-overrides layer, so they win over the SDK's own rules once the SDK's stylesheet is in an earlier layer, as Theming → CSS layers sets up. They take their colors, spacing and type from the SDK's tokens, so they follow your theme; the card's text uses --str-chat__chat-text-system, the color the SDK gives system text such as date separators.

Wrap the channel in it, so every message list inside renders system messages with CustomSystemMessage:

src/ChannelWithSystemMessages.tsx
import type { Channel as StreamChannel } from "stream-chat";
import { Channel, MessageComposer, MessageList } from "stream-chat-react";
import { WithCustomSystemMessages } from "./CustomSystemMessage";

export const ChannelWithSystemMessages = ({
  channel,
}: {
  channel: StreamChannel;
}) => (
  <WithCustomSystemMessages>
    <Channel channel={channel}>
      <MessageList />
      <MessageComposer />
    </Channel>
  </WithCustomSystemMessages>
);
Note:

To see it, mute a user with the /mute command followed by an @mention. The command has to be enabled for the channel type in the Dashboard.

How it works

  1. The list renders MessageSystem for every message of type system, and passes the message as message. Unlike a message UI, it renders outside MessageContext, so the message comes from its props.
  2. created_at is a nanosecond number, so convertTimestampToDate turns it into a date; Data conventions explains why. The component shows the date's hour and minute in the user's locale, with a numeric hour, as the SDK's own message timestamps do.
  3. message.user is the user the server sent the message as. A system message your backend sends without a user has none, so only the time is shown under the text.

When unsafeHTML is set on <MessageList/> or <VirtualizedMessageList/>, the list passes it to MessageSystem too. Without it, the prop is absent. To render a system message's html the way the default does, read that prop as well, and render the text when the message has no html. Message props says when unsafeHTML is safe to turn on.

Related