This is beta documentation for Stream Chat React SDK v14. For the latest stable version, see the latest version (v13) .

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".

Custom System Message Component

Our custom component shows the message text, date, and actor (user who triggered the event). Register it with WithComponents so the nested MessageList or VirtualizedMessageList can read it from 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,
  WithComponents,
} 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
          imageUrl={user?.image}
          size="sm"
          userName={user?.name || user?.id}
        />
        {user?.name}
      </div>
    </div>
  );
};

//...

<WithComponents overrides={{ MessageSystem: CustomSystemMessage }}>
  <Channel>...</Channel>
</WithComponents>;

.custom-system-message__actor {
  display: flex;
  gap: 0.5rem;
}

.custom-system-message {
  padding: 1rem;
  display: flex;
  flex-direction: column;
  align-items: center;
  border-radius: var(--str-chat__border-radius-md);
  background: red; /* For browsers that do not support gradients */
  background: -webkit-linear-gradient(
    left,
    orange,
    yellow,
    green,
    cyan,
    blue,
    violet
  ); /* For Safari 5.1 to 6.0 */
  background: -o-linear-gradient(
    right,
    orange,
    yellow,
    green,
    cyan,
    blue,
    violet
  ); /* For Opera 11.1 to 12.0 */
  background: -moz-linear-gradient(
    right,
    orange,
    yellow,
    green,
    cyan,
    blue,
    violet
  ); /* For Firefox 3.6 to 15 */
  background: linear-gradient(
    to right,
    orange,
    yellow,
    green,
    cyan,
    blue,
    violet
  ); /* Standard syntax (must be last) */
}

Pin Indicator

Message List Notifications