Could you ask @Maria and @Design to review #launch before the call?
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
bunx --bun @getweini/cli@latest add mention-textStart 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.
<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.
<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>Repeated labels and safe links
Entities with the same label keep distinct IDs. Relative and web links render as links; unsafe schemes remain styled text.
<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
| Name | Type or signature | Default | What it does |
|---|---|---|---|
textprop | string | Required | Controls the text behavior of MentionText. |
mentionsprop | readonly MentionRange[] | undefined | [] | Controls the mentions behavior of MentionText. |
mentionslot | ((props: { entity: MentionRange["entity"]; mention: MentionRange; text: string; }) => unknown) | undefined | Optional | Content for the mention area of MentionText. |
Public type definitions
// 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.