System Message

A system message is generated by backend events (for example, banning or muting a user). The SDK renders them automatically in VirtualizedMessageList and MessageList. This guide shows how to override the default component.

Best Practices

  • Keep system messages visually distinct but not disruptive.
  • Preserve the message text and timestamp for audit clarity.
  • Avoid exposing sensitive actor details unless your policy allows it.
  • Use MessageSystem override for layout changes, not just styling.
  • Test system messages for moderation events and permission changes.

Default System Message Component

The default system message component is EventComponent. It renders when message.type === "system".

Default System Message

Custom System Message Component

Our custom component shows the message text, date, and actor (user who triggered the event). To override the default, pass MessageSystem to Channel, which injects it into ComponentContext.

To see your component in action, try muting a user with the /mute command followed by an @mention. These commands must be enabled in the Dashboard.

import { Avatar as DefaultAvatar, Channel } from "stream-chat-react";
import type { EventComponentProps } from "stream-chat-react";

const CustomSystemMessage = (props: EventComponentProps) => {
  const { Avatar = DefaultAvatar, message } = props;

  const { created_at = "", text, user } = message;
  const date = created_at.toString();

  return (
    <div className="custom-system-message">
      <div>
        Event: <strong>{text?.trim()}</strong> at {date}
      </div>
      <div className="custom-system-message__actor">
        Actor:
        <Avatar image={user?.image} />
        {user?.name}
      </div>
    </div>
  );
};

//...

<Channel MessageSystem={CustomSystemMessage}>...</Channel>;

Custom System Message

Previous
Pin Indicator
Next
Message List Notifications