---
url: https://talkjs.com/docs/Guides/Web_Components/Customizing_Mentions
---

# Customizing mentions

Customize who users can mention and notify mentioned non-participants.

Ask a question Copy for LLM [View as Markdown](/docs/Guides/Web_Components/Customizing_Mentions.md)
By default, users can mention the participants in a conversation. You can also
let them mention people who aren't currently participants, or otherwise control the contents of the mentions dropdown.

## Mention people outside a conversation

Use the [`transformMentions`](/docs/UI_Components/Web_Components/t-chatbox/#ChatboxProps__transformMentions) property to add people to the mention suggestions:

```html
<t-chatbox
  id="chatbox"
  app-id="<APP_ID>"
  user-id="sample_user_alice"
  conversation-id="sample_conversation"
></t-chatbox>

<script type="module">
  import '@talkjs/web-components';

  const mentionableNonParticipants = [
    { id: 'john', name: 'John' },
    { id: 'ada', name: 'Ada' },
  ];

  const chatbox = document.querySelector('#chatbox');
  chatbox.transformMentions = (suggestions) => [
    ...suggestions,
    ...mentionableNonParticipants,
  ];
</script>
```

This only adds the people to the mention suggestions. It doesn't add them to
the conversation or notify them when they're mentioned.

Note: the callback may be called at any time and any number of times, and possibly with an
incomplete participant list (eg while loading). It must have no side effects.

## Notify mentioned non-participants

To notify a mentioned non-participant, add them to the conversation just before
the message is sent. Use [`beforeSendMessage`](/docs/UI_Components/Web_Components/t-chatbox/#ChatboxProps__beforeSendMessage) to find mentions in the message content, and the [Data API](/docs/JavaScript_Data_API/Participants/#ParticipantRef__createIfNotExists) to add every mentioned user as a participant:

```html
<t-chatbox
  id="chatbox"
  app-id="<APP_ID>"
  user-id="sample_user_alice"
  conversation-id="sample_conversation"
></t-chatbox>

<script type="module">
  import { getTalkSession } from '@talkjs/core';
  import '@talkjs/web-components';

  const appId = '<APP_ID>';
  const userId = 'sample_user_alice';
  const conversationId = 'sample_conversation';
  const mentionableNonParticipants = [
    { id: 'john', name: 'John' },
    { id: 'ada', name: 'Ada' },
  ];

  const session = getTalkSession({ appId, userId });
  const conversation = session.conversation(conversationId);
  const chatbox = document.querySelector('#chatbox');

  chatbox.transformMentions = (suggestions) => [
    ...suggestions,
    ...mentionableNonParticipants,
  ];
  chatbox.beforeSendMessage = (message) => {
    const mentions = getMentions(message.content);
    for (const userId of mentions) {
      conversation.participant(userId).createIfNotExists();
    }
  };

  function getMentions(nodes) {
    return nodes.flatMap((node) => {
      if (typeof node === 'string') return [];
      if (node.type === 'mention') return [node.id];
      return 'children' in node ? getMentions(node.children) : [];
    });
  }
</script>
```

You don't need to await `createIfNotExists()`. The Web Component and Data API
share a session, and the Data API's pipelining preserves the order of these
operations, so the participant is added before the message is sent.

The person must already exist as a TalkJS user before you can add them as a
participant.