Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Display

MentionText

An entity can include an optional avatar URL, such as { id: 'person-maria', label: 'Maria', avatar: '/avatars/maria.jpg' }. MentionText displays it as a decorative 16px rounded avatar beside the padded, rounded mention. If the image fails to load, an initial appears instead.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

Could you ask @Maria and @Design to review #launch before the call?

Install

Run in your project
bunx --bun @getweini/cli@latest add mention-text

Start with this example

Pass the message text and mention ranges from your saved message. The ranges use JavaScript string offsets, and the visible text at each range must match its trigger and entity label.

Alex Morgan

Could you ask @Maria and @Design to review #launch before the call?

Vue
<script setup lang="ts">
import MentionText from './components/ui/mention-text/MentionText.vue'

const mariaAvatar = `data:image/svg+xml,${encodeURIComponent(
  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" fill="#e4e4e7"/><circle cx="32" cy="23" r="12" fill="#71717a"/><path d="M9 64c2-15 10-23 23-23s21 8 23 23" fill="#71717a"/></svg>',
)}`

const message = {
  text: 'Could you ask @Maria and @Design to review #launch before the call?',
  mentions: [
    {
      start: 14,
      end: 20,
      trigger: '@',
      entity: { id: 'person-maria', label: 'Maria', kind: 'person', avatar: mariaAvatar },
    },
    {
      start: 25,
      end: 32,
      trigger: '@',
      entity: { id: 'team-design', label: 'Design', kind: 'team' },
    },
    {
      start: 43,
      end: 50,
      trigger: '#',
      entity: { id: 'project-launch', label: 'launch', kind: 'project', href: '#' },
    },
  ],
}
</script>

<template>
  <article class="max-w-lg rounded-xl border border-border bg-card p-4 text-card-foreground">
    <div class="mb-2 flex items-center justify-between gap-3 text-xs text-muted-foreground">
      <span class="font-medium text-foreground">Alex Morgan</span>
      <time>10:42 AM</time>
    </div>
    <p class="text-sm leading-6">
      <MentionText :text="message.text" :mentions="message.mentions" />
    </p>
  </article>
</template>

Pass the message text and mention ranges from your saved message. The ranges use JavaScript string offsets, and the visible text at each range must match its trigger and entity label.

When to use it

Group conversations

Render people and team references in a message after it has been sent.

Activity and comments

Show linked projects, tickets, or documents while retaining the original message text for copying and search.

More examples

Customize mention rendering

Use the mention slot when your application needs its own link or visual treatment.

Customize mention rendering
<script setup lang="ts">
import MentionText from './components/ui/mention-text/MentionText.vue'

const message = {
  text: 'I added @Maria to the review and linked #launch.',
  mentions: [
    {
      start: 8,
      end: 14,
      trigger: '@',
      entity: { id: 'person-maria', label: 'Maria', kind: 'person', href: '/people/maria' },
    },
    {
      start: 40,
      end: 47,
      trigger: '#',
      entity: { id: 'project-launch', label: 'launch', kind: 'project' },
    },
  ],
}
</script>

<template>
  <p class="text-sm leading-6">
    <MentionText :text="message.text" :mentions="message.mentions">
      <template #mention="{ entity, text }">
        <a
          v-if="entity.href"
          :href="entity.href"
          class="font-medium text-primary underline underline-offset-2"
        >
          {{ text }}
        </a>
        <span v-else class="rounded-sm bg-accent px-1 text-accent-foreground">{{ text }}</span>
      </template>
    </MentionText>
  </p>
</template>

Entities with the same label keep distinct IDs. Relative and web links render as links; unsafe schemes remain styled text.

Repeated labels and safe links
<script setup lang="ts">
import MentionText from './components/ui/mention-text/MentionText.vue'

const text = 'Ask @Jordan to coordinate with @Jordan about #launch.'
const mentions = [
  {
    start: 4,
    end: 11,
    trigger: '@',
    entity: { id: 'person-jordan', label: 'Jordan', kind: 'person', href: '/people/jordan' },
  },
  {
    start: 31,
    end: 38,
    trigger: '@',
    entity: { id: 'team-jordan', label: 'Jordan', kind: 'team', href: 'javascript:alert(1)' },
  },
  {
    start: 45,
    end: 52,
    trigger: '#',
    entity: { id: 'project-launch', label: 'launch', kind: 'project' },
  },
]
</script>

<template>
  <p class="text-sm leading-6">
    <MentionText :text="text" :mentions="mentions" />
  </p>
</template>

Complete API

Every public prop, slot, and native attribute of the installed Vue component is listed below.

MentionText

Complete API for MentionText
NameType or signatureDefaultWhat it does
textpropstringRequiredControls the text behavior of MentionText.
mentionspropreadonly MentionRange[] | undefined[]Controls the mentions behavior of MentionText.
mentionslot((props: { entity: MentionRange["entity"]; mention: MentionRange; text: string; }) => unknown) | undefinedOptionalContent for the mention area of MentionText.
Public type definitions
Public types
// packages/frameworks/vue/components/mention-text/types.ts
import type { MentionRange } from '@getweini/vue/primitives/mention'

export type { MentionEntity, MentionRange, MentionSegment } from '@getweini/vue/primitives/mention'

export interface MentionTextProps {
  text: string
  mentions?: readonly MentionRange[]
}

export interface MentionTextSlots {
  mention?(props: { entity: MentionRange['entity']; mention: MentionRange; text: string }): unknown
}


// packages/frameworks/vue/dist/vue/primitives/mention/index.d.ts
import type { MentionEditRange, MentionRange, MentionSegment } from './types';
export type { MentionEditRange, MentionEntity, MentionRange, MentionSegment } from './types';
/** Keep only valid mention ranges, in text order, dropping overlaps deterministically. */
export declare function normalizeMentions(text: string, mentions: readonly MentionRange[]): MentionRange[];
/** Split plain text around valid mentions without changing or losing any characters. */
export declare function getMentionSegments(text: string, mentions: readonly MentionRange[]): MentionSegment[];
/** Apply the smallest contiguous text edit to mention offsets, dropping edited mentions. */
export declare function updateMentionRanges(previousText: string, nextText: string, mentions: readonly MentionRange[], edit?: MentionEditRange): MentionRange[];
/** Allow ordinary relative links and http(s)/mailto URLs while rejecting executable schemes. */
export declare function isSafeMentionHref(href: string | undefined): href is string;


// packages/frameworks/vue/dist/vue/primitives/mention/types.d.ts
export interface MentionEntity {
    id: string;
    label: string;
    kind?: string;
    description?: string;
    avatar?: string;
    href?: string;
    disabled?: boolean;
}
/** A mention's UTF-16 range in the plain message text. */
export interface MentionRange {
    start: number;
    end: number;
    trigger: string;
    entity: MentionEntity;
}
export interface MentionSegment {
    text: string;
    mention?: MentionRange;
}
/** UTF-16 selection in the previous text that the user replaced. */
export interface MentionEditRange {
    start: number;
    end: number;
}

Implementation notes

  • Store structured mention ranges alongside the message text; each range includes a stable entity ID.
  • If a mention's visible text changes, update the range and label together. A range that no longer matches is shown as ordinary text.
  • Links are rendered only for safe relative, HTTP(S), or mailto URLs. Unsafe schemes remain styled text.
  • Offsets count UTF-16 code units, as used by JavaScript string indexing.

Accessibility and localization

  • Keep entity labels meaningful: they become the visible text and accessible name of a mention link.
  • If the mention slot renders a link, retain native link semantics and a visible keyboard focus indicator.

Source contract and editing guidance