Mentions Actions

This example shows how to run custom functions on mention hover and click. Pass onMentionsHover and onMentionsClick to Channel, MessageList, or VirtualizedMessageList.

Both handlers receive the event, an array of the message's mentioned users, and the message. The second argument is deprecated in favor of the third message argument. Use the message argument for the mentioned users (message.mentioned_users) as well as @channel, @here, role, and user-group metadata.

Best Practices

  • Keep mention handlers lightweight to avoid blocking message rendering.
  • Use dataset userId to reliably target a direct user mention.
  • Use the message argument for non-user mentions such as mentioned_channel, mentioned_here, mentioned_roles, and mentioned_groups.
  • Prefer navigation or preview actions over intrusive alerts in production.
  • Avoid mutating styles directly unless it’s a deliberate UX effect.
  • Use a custom Mention component for richer interactions.

Mention Click Action

This example targets the clicked user and shows their name via window.alert. Click handlers are useful for navigation to a profile page.

import type { BaseSyntheticEvent } from "react";
import type { LocalMessage, UserResponse } from "stream-chat";
import { Channel } from "stream-chat-react";

type MentionAction = (
  event: BaseSyntheticEvent,
  // Deprecated: prefer `message.mentioned_users` from the third argument.
  mentionedUsers: UserResponse[],
  message: LocalMessage,
) => void;

const handleMentionsClick: MentionAction = (
  event,
  _mentionedUsers,
  message,
) => {
  const userId = event.target.dataset.userId;

  if (!userId) {
    if (message.mentioned_channel) {
      window.alert("Mentioned the whole channel");
    }
    return;
  }

  const mentionedUser = message.mentioned_users?.find(
    (user) => user.id === userId,
  );

  if (!mentionedUser) return;

  window.alert(`Mentioned user: ${mentionedUser.name || mentionedUser.id}`);
};

export const WrappedChannel = ({ children }) => {
  return <Channel onMentionsClick={handleMentionsClick}>{children}</Channel>;
};

Mention Hover Action

For a simple hover example, we’ll randomly change the mention text color via the event target.

import type { BaseSyntheticEvent } from "react";
import type { LocalMessage, UserResponse } from "stream-chat";
import { Channel } from "stream-chat-react";

type MentionAction = (
  event: BaseSyntheticEvent,
  // Deprecated: prefer `message.mentioned_users` from the third argument.
  mentionedUsers: UserResponse[],
  message: LocalMessage,
) => void;

const handleMentionsHover: MentionAction = (event) => {
  if (!event.target.dataset.userId) return;

  const randomColor = Math.floor(Math.random() * 16777215).toString(16);
  event.target.style.color = `#${randomColor}`;
};

export const WrappedChannel = ({ children }) => {
  return <Channel onMentionsHover={handleMentionsHover}>{children}</Channel>;
};

Custom Mention Component

If you need more control or access to contexts like MessageContext, use a custom Mention component. See Custom Element Rendering.

Previous
Reactions Customization
Next
Message Actions