Vue EditorMentionMenu Component

Usage

The EditorMentionMenu component displays a menu of user suggestions when typing a trigger character (defaults to @) in the editor and inserts the selected mention using the @tiptap/extension-mention package. The trigger character is also used as the prefix when rendering the inserted mention.

It uses the useEditorMenu composable built on top of TipTap's Suggestion utility to filter items as you type and support keyboard navigation (arrow keys, enter to select, escape to close).

It must be used inside an Editor component's default slot to have access to the editor instance.

<script setup lang="ts">
import type { EditorMentionMenuItem } from '@bitrix24/b24ui-nuxt'

const value = ref(`# Mention Menu

Type @ to mention someone and select from the list of available users.`)

const items: EditorMentionMenuItem[] = [
  {
    label: 'bitrix24',
    avatar: {
      src: 'https://github.com/bitrix24.png',
      loading: 'lazy' as const
    }
  },
  {
    label: 'Employee',
    avatar: {
      src: '/b24ui/avatar/employee.png',
      loading: 'lazy' as const
    }
  },
  {
    label: 'Assistant',
    avatar: {
      src: '/b24ui/avatar/assistant.png',
      loading: 'lazy' as const
    }
  }
]

// SSR-safe function to append menus to body (avoids z-index issues in docs)
const appendToBody = import.meta.client ? () => document.body : undefined
</script>

<template>
  <B24Editor
    v-slot="{ editor }"
    v-model="value"
    content-type="markdown"
    placeholder="Type @ to mention someone..."
    class="w-full min-h-21"
  >
    <B24EditorMentionMenu :editor="editor" :items="items" :append-to="appendToBody" />
  </B24Editor>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { EditorMentionMenuItem } from '@bitrix24/b24ui-nuxt'

const value = ref(`# Mention Menu

Type @ to mention someone and select from the list of available users.`)

const items: EditorMentionMenuItem[] = [
  {
    label: 'bitrix24',
    avatar: {
      src: 'https://github.com/bitrix24.png',
      loading: 'lazy' as const
    }
  },
  {
    label: 'Employee',
    avatar: {
      src: '/b24ui/avatar/employee.png',
      loading: 'lazy' as const
    }
  },
  {
    label: 'Assistant',
    avatar: {
      src: '/b24ui/avatar/assistant.png',
      loading: 'lazy' as const
    }
  }
]

// SSR-safe function to append menus to body (avoids z-index issues in docs)
const appendToBody = import.meta.client ? () => document.body : undefined
</script>

<template>
  <B24Editor
    v-slot="{ editor }"
    v-model="value"
    content-type="markdown"
    placeholder="Type @ to mention someone..."
    class="w-full min-h-21"
  >
    <B24EditorMentionMenu :editor="editor" :items="items" :append-to="appendToBody" />
  </B24Editor>
</template>

Learn more about the Mention extension in the TipTap documentation.

Items

Use the items prop as an array of objects with the following properties:

label: string
avatar?: AvatarProps
icon?: IconComponent
description?: string
disabled?: boolean

<script setup lang="ts">
import type { EditorMentionMenuItem } from '@bitrix24/b24ui-nuxt'

const value = ref(`Type @ to mention a user.

You can customize the items with avatars, icons, and descriptions.`)

const items: EditorMentionMenuItem[] = [
  {
    label: 'bitrix24',
    avatar: { src: 'https://github.com/bitrix24.png', loading: 'lazy' as const },
    description: 'Bitrix24 profile'
  },
  {
    label: 'Employee',
    avatar: { src: '/b24ui/avatar/employee.png', loading: 'lazy' as const }
  },
  {
    label: 'Assistant',
    avatar: { src: '/b24ui/avatar/assistant.png', loading: 'lazy' as const },
    disabled: true
  }
]
</script>

<template>
  <B24Editor
    v-slot="{ editor }"
    v-model="value"
    content-type="markdown"
    placeholder="Type @ to mention..."
    class="w-full min-h-19"
  >
    <B24EditorMentionMenu :editor="editor" :items="items" />
  </B24Editor>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { EditorMentionMenuItem } from '@bitrix24/b24ui-nuxt'

const value = ref(`Type @ to mention a user.

You can customize the items with avatars, icons, and descriptions.`)

const items: EditorMentionMenuItem[] = [
  {
    label: 'bitrix24',
    avatar: { src: 'https://github.com/bitrix24.png', loading: 'lazy' as const },
    description: 'Bitrix24 profile'
  },
  {
    label: 'Employee',
    avatar: { src: '/b24ui/avatar/employee.png', loading: 'lazy' as const }
  },
  {
    label: 'Assistant',
    avatar: { src: '/b24ui/avatar/assistant.png', loading: 'lazy' as const },
    disabled: true
  }
]
</script>

<template>
  <B24Editor
    v-slot="{ editor }"
    v-model="value"
    content-type="markdown"
    placeholder="Type @ to mention..."
    class="w-full min-h-19"
  >
    <B24EditorMentionMenu :editor="editor" :items="items" />
  </B24Editor>
</template>

You can also pass an array of arrays to the items prop to create separated groups of items.

Char

Use the char prop to change the trigger character. Defaults to @. The trigger character is also used as the prefix when rendering the inserted mention (e.g. #channel instead of @channel).

<template>
  <B24Editor v-slot="{ editor }">
    <B24EditorMentionMenu :editor="editor" :items="channels" char="#" />
  </B24Editor>
</template>

You can use multiple EditorMentionMenu components on the same editor with different char and plugin-key props to support different mention types.

<template>
  <B24Editor v-slot="{ editor }">
    <B24EditorMentionMenu :editor="editor" :items="users" plugin-key="mentionMenu" />
    <B24EditorMentionMenu :editor="editor" :items="tags" char="#" plugin-key="tagMenu" />
  </B24Editor>
</template>

Suggestion Soon

Use the suggestion prop to customize TipTap's Suggestion matching behavior.

This is useful when the trigger character should open directly after other characters instead of requiring the default whitespace prefix.

<template>
  <B24Editor v-slot="{ editor }">
    <B24EditorMentionMenu
      :editor="editor"
      :items="items"
      char="#"
      :suggestion="{
        allowedPrefixes: null
      }"
    />
  </B24Editor>
</template>

Options

Use the options prop to customize the positioning behavior using Floating UI options.

<template>
  <B24Editor v-slot="{ editor }">
    <B24EditorMentionMenu
      :editor="editor"
      :items="items"
      :options="{
        placement: 'bottom-start',
        offset: 4
      }"
    />
  </B24Editor>
</template>

Examples

With ignore filter

You can set the ignore-filter prop to true to disable the internal search and use your own search logic. Use v-model:search-term to access the current search term and fetch items from an API.

<script setup lang="ts">
import { refDebounced } from '@vueuse/core'

const value = ref(`# Async Mention Menu

Type @ to mention someone. Results are fetched from an API as you type.`)

const searchTerm = ref('')
const searchTermDebounced = refDebounced(searchTerm, 200)

const { data: items } = useLazyFetch('https://dummyjson.com/users/search?limit=10', {
  key: 'editor-mention-users-search',
  params: { q: searchTermDebounced },
  transform: (data: { users: { id: number, firstName: string, lastName: string, image: string }[] }) => {
    return data.users?.map(user => ({ id: user.id, label: `${user.firstName} ${user.lastName}`, avatar: { src: user.image, loading: 'lazy' as const } })) || []
  },
  server: false
})

// SSR-safe function to append menus to body (avoids z-index issues in docs)
const appendToBody = import.meta.client ? () => document.body : undefined
</script>

<template>
  <B24Editor
    v-slot="{ editor }"
    v-model="value"
    content-type="markdown"
    placeholder="Type @ to mention..."
    class="w-full min-h-21"
  >
    <B24EditorMentionMenu
      v-model:search-term="searchTerm"
      :editor="editor"
      :items="items"
      :append-to="appendToBody"
      ignore-filter
    />
  </B24Editor>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { refDebounced } from '@vueuse/core'

const value = ref(`# Async Mention Menu

Type @ to mention someone. Results are fetched from an API as you type.`)

const searchTerm = ref('')
const searchTermDebounced = refDebounced(searchTerm, 200)

const { data: items } = useLazyFetch('https://dummyjson.com/users/search?limit=10', {
  key: 'editor-mention-users-search',
  params: { q: searchTermDebounced },
  transform: (data: { users: { id: number, firstName: string, lastName: string, image: string }[] }) => {
    return data.users?.map(user => ({ id: user.id, label: `${user.firstName} ${user.lastName}`, avatar: { src: user.image, loading: 'lazy' as const } })) || []
  },
  server: false
})

// SSR-safe function to append menus to body (avoids z-index issues in docs)
const appendToBody = import.meta.client ? () => document.body : undefined
</script>

<template>
  <B24Editor
    v-slot="{ editor }"
    v-model="value"
    content-type="markdown"
    placeholder="Type @ to mention..."
    class="w-full min-h-21"
  >
    <B24EditorMentionMenu
      v-model:search-term="searchTerm"
      :editor="editor"
      :items="items"
      :append-to="appendToBody"
      ignore-filter
    />
  </B24Editor>
</template>

This example uses refDebounced to debounce the API calls.

API

Props

Prop	Default	Type
`size`	`'md'`	`"xs" \| "md" \| "xss" \| "sm" \| "lg" \| "xl"`
`items`		`T[] \| T[][]`
`editor`		`Editor`
`char`	`'@'`	`string` The trigger character (e.g., '/', '@', ':')
`pluginKey`	`'mentionMenu'`	`string` Plugin key to identify this menu
`filterFields`	`['label']`	`string[]` Fields to filter items by.
`limit`	`42`	`number` Maximum number of items to display
`options`	`{ strategy: 'absolute', placement: 'bottom-start', offset: 8, shift: { padding: 8 } }`	`FloatingUIOptions` The options for positioning the menu. Those are passed to Floating UI and include options for the placement, offset, flip, shift, size, autoPlacement, hide, and inline middleware.
`suggestion`		`Omit<Partial<SuggestionOptions<any, any>>, "editor" \| "char" \| "pluginKey" \| "items" \| "command" \| "render">` Optional TipTap Suggestion matching options.
`appendTo`		`HTMLElement \| (): HTMLElement` The DOM element to append the menu to. Default is the editor's parent element. Sometimes the menu needs to be appended to a different DOM context due to accessibility, clipping, or z-index issues.
`b24ui`		`{ content?: ClassNameValue; viewport?: ClassNameValue; group?: ClassNameValue; label?: ClassNameValue; item?: ClassNameValue; itemLeadingIcon?: ClassNameValue; itemLeadingAvatar?: ClassNameValue; itemLeadingAvatarSize?: ClassNameValue; itemWrapper?: ClassNameValue; itemLabel?: ClassNameValue; itemDescription?: ClassNameValue; itemLabelExternalIcon?: ClassNameValue; }`

Theme

https://github.com/bitrix24/b24ui/tree/main/src/theme/editor-mention-menu.ts

export default {
  slots: {
    content: 'base-mode bg-(--ui-color-bg-content-primary) shadow-(--popup-window-box-shadow) rounded-(--ui-border-radius-xl) will-change-[opacity] motion-safe:data-[state=open]:animate-[scale-in_100ms_ease-out] motion-safe:data-[state=closed]:animate-[scale-out_100ms_ease-in] origin-(--reka-dropdown-menu-content-transform-origin) font-[family-name:var(--ui-font-family-primary)] relative isolate px-0 py-(--menu-popup-padding) pointer-events-auto',
    viewport: 'relative w-full max-h-[40vh] min-w-48 max-w-60 overflow-x-hidden overflow-y-auto scrollbar-thin',
    group: 'grid',
    label: 'w-full h-(--popup-window-delimiter-section-height) mt-(--menu-item-block-stack-space) flex flex-row rtl:flex-row-reverse items-center select-none outline-none whitespace-nowrap text-start text-(--b24ui-typography-legend-color) font-(--ui-font-weight-normal) after:ms-[10px] after:block after:flex-1 after:min-w-[15px] after:h-px after:bg-(--ui-color-divider-vibrant-default)',
    item: 'group w-full  mt-(--menu-item-block-stack-space) relative flex flex-row rtl:flex-row-reverse items-center select-none outline-none whitespace-nowrap cursor-pointer data-disabled:cursor-not-allowed data-disabled:opacity-30 text-start text-(--b24ui-typography-legend-color) hover:text-(--b24ui-typography-label-color) data-highlighted:text-(--b24ui-typography-label-color) data-[state=open]:text-(--b24ui-typography-label-color) hover:bg-(--ui-color-divider-optical-1-alt) data-highlighted:bg-(--ui-color-divider-optical-1-alt) data-[state=open]:bg-(--ui-color-divider-optical-1-alt) transition-colors',
    itemLeadingIcon: 'shrink-0 text-(--ui-color-design-plain-content-icon-secondary) group-data-highlighted:text-(--ui-color-accent-main-primary) group-data-[state=open]:text-(--ui-color-accent-main-primary) group-data-[state=checked]:text-(--ui-color-accent-main-primary) transition-colors',
    itemLeadingAvatar: 'shrink-0',
    itemLeadingAvatarSize: '',
    itemWrapper: 'ms-[4px] flex-1 flex flex-col text-start min-w-0',
    itemLabel: 'max-w-60 truncate -mt-px group-data-[state=checked]:text-(--ui-color-accent-main-primary)',
    itemDescription: 'max-w-60 truncate -mt-[6px] text-(--b24ui-typography-description-color) text-(length:--ui-font-size-sm)',
    itemLabelExternalIcon: 'inline-block size-[16px] text-(--ui-color-design-plain-content-icon-secondary)'
  },
  variants: {
    size: {
      xss: {
        label: 'px-[14px] text-(length:--ui-font-size-4xs)/[normal] gap-[14px]',
        item: 'px-[14px] :text-(length:--ui-font-size-4xs)/[normal] gap-[14px]',
        itemLeadingIcon: 'size-4 text-(length:--ui-font-size-sm)/[normal]',
        itemLeadingAvatarSize: '3xs'
      },
      xs: {
        label: 'px-[14px] text-(length:--ui-font-size-4xs)/[normal] gap-[14px]',
        item: 'px-[14px] :text-(length:--ui-font-size-xs)/[normal] gap-[14px]',
        itemLeadingIcon: 'size-4 text-(length:--ui-font-size-sm)/[normal]',
        itemLeadingAvatarSize: '3xs'
      },
      sm: {
        label: 'px-4.5 text-(length:--ui-font-size-xs)/[normal] gap-4.5',
        item: 'px-4.5 :text-(length:--ui-font-size-xs)/[normal] gap-4.5',
        itemLeadingIcon: 'size-4 text-(length:--ui-font-size-sm)/[normal]',
        itemLeadingAvatarSize: '3xs'
      },
      md: {
        label: 'px-4.5 text-(length:--ui-font-size-sm)/[normal] gap-4.5',
        item: 'h-[36px] px-4.5 text-(length:--ui-font-size-sm)/[normal] gap-4.5',
        itemLeadingIcon: 'size-4.5 text-(length:--ui-font-size-lg)/[normal]',
        itemLeadingAvatar: 'size-[16px] me-2',
        itemLeadingAvatarSize: '2xs'
      },
      lg: {
        label: 'px-[20px] :text-(length:--ui-font-size-sm)/[normal] gap-[20px]',
        item: 'px-[20px] text-(length:--ui-font-size-sm)/[normal] gap-[20px]',
        itemLeadingIcon: 'size-4.5 text-(length:--ui-font-size-lg)/[normal]',
        itemLeadingAvatar: 'size-[16px] me-2',
        itemLeadingAvatarSize: '2xs'
      },
      xl: {
        label: 'px-[20px] text-(length:--ui-font-size-sm)/[normal] gap-[20px]',
        item: 'px-[20px] text-(length:--ui-font-size-lg)/[normal] gap-[20px]',
        itemLeadingIcon: 'size-[20px] text-(length:--ui-font-size-2xl)/[normal]',
        itemLeadingAvatar: 'size-[16px] me-2',
        itemLeadingAvatarSize: 'xs'
      }
    },
    active: {
      true: {
        item: 'text-(--ui-color-accent-main-primary) hover:text-(--ui-color-accent-main-primary)',
        itemLeadingIcon: 'text-(--ui-color-accent-main-primary) hover:text-(--ui-color-accent-main-primary) group-data-[state=open]:text-(--ui-color-accent-main-primary)'
      },
      false: {}
    }
  },
  defaultVariants: {
    size: 'md'
  }
}

EditorEmojiMenu

An emoji suggestion menu that automatically appears upon typing the colon : character in the editor.

EditorSuggestionMenu

A slash command menu that displays formatting and action suggestions when typing /.