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, the matched direct user, and the message. The second argument is kept for backwards compatibility and is only populated for direct user mentions. Use the third message argument for @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,
  user?: UserResponse,
  message?: LocalMessage,
) => void;

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

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

  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,
  user?: 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