Mentions

A mention points a message at people: a user, everyone in the channel, everyone online, a role or a user group. The user types @, picks from the suggestions, and the message goes out with the mention, so the server can notify the people it names.

Kinds of mentions

The mentions middleware opens the suggestions after @. A picked mention is inserted as @ and its name, and kept in textComposer.mentions (see Text). When the message is sent, every mention still present in the text goes with it.

The capabilities come from channel.data.own_capabilities and are read at each query, so the list follows a change of the user's permissions.

Where the suggestions come from

• Users. When the channel's query loaded all its members (fewer than 100), the members and watchers are searched locally, without a request, and the current user is left out. Larger channels query the members by name. An @ with nothing typed after it always lists the loaded members and watchers, whatever the channel's size.
• @channel and @here appear on the first page, when they start with what was typed.
• Roles are searched with client.searchRoles(), and user groups with client.searchUserGroups(), among the groups of the channel's team when it has one. Both start once something is typed after @. Roles appear on the first page only.

Muted users aren't offered. After /unmute, only muted users are. If the role or group search fails, the other suggestions still appear.

Customizing mention search

MentionsSearchSource loads the mention suggestions. To change what is searched, give the mentions middleware a search source of your own, created with these options:

In this sample, transliterate removes accents the built-in step keeps, such as the carons in Czech names, and the search covers every user of the app. Replace the middleware in the composer setup function. MiddlewareExecutor.replace() puts the new middleware in the place of the built-in one, because both have the same id:

import {
  createMentionsMiddleware,
  MentionsSearchSource,
  StreamChat,
} from "stream-chat";
import type { TextComposerMiddleware } from "stream-chat";

const client = StreamChat.getInstance("YOUR_API_KEY");

const removeAccents = (text: string) =>
  text.normalize("NFD").replace(/[\u0300-\u036f]/g, "");

client.config.setSetupFunction("messageComposer", ({ composer }) => {
  const { channel, textComposer } = composer;
  const searchSource = new MentionsSearchSource(channel, {
    mentionAllAppUsers: true,
    pageSize: 20,
    transliterate: removeAccents,
  });

  textComposer.middlewareExecutor.replace([
    createMentionsMiddleware(channel, {
      searchSource,
    }) as TextComposerMiddleware,
  ]);

  return () =>
    textComposer.middlewareExecutor.replace([
      createMentionsMiddleware(channel) as TextComposerMiddleware,
    ]);
});

For more control, extend MentionsSearchSource and override one of its steps:

import { MentionsSearchSource } from "stream-chat";
import type { MentionSuggestion } from "stream-chat";

class WithoutBotsSearchSource extends MentionsSearchSource {
  filterQueryResults(items: MentionSuggestion[]) {
    return super
      .filterQueryResults(items)
      .filter((item) => item.mentionType !== "user" || item.role !== "bot");
  }
}

Suggestions explains the minChars and trigger options of the mentions middleware. The SDK's AutoCompleteSuggestionItem renders each suggestion, and Custom suggestions shows how to replace it.

Pitfalls

• A search source per composer. Create the search source inside the setup function, as the example does, so composers don't share results.

Used in

• Mentions