Preview Updated 2026-05-10

Mention

Multi-line text input that opens a candidate dropdown when the trigger character (default @) is typed; ↑↓ to select, Enter / Tab to confirm.

Basic usage

CfMention overlays trigger-character recognition on a <textarea>. When @ appears before the cursor followed by an optional search string (no spaces), the dropdown opens and filters options by case-insensitive substring on that text.

When an option is picked, @<value> is inserted at the cursor — replacing the segment from the trigger to the current cursor position only, leaving subsequent text untouched.

背景

<script setup lang="ts">
import { ref } from 'vue';
import { CfMention } from '@chufix-design/vue';

const text = ref('在评论里输入 @ 试试');
const options = [
  { value: 'alice', label: 'Alice 张', description: '前端 · 设计系统' },
  { value: 'bob', label: 'Bob 李', description: '后端 · API 网关' },
  { value: 'carol', label: 'Carol 刘', description: '产品' },
  { value: 'david', label: 'David 王', description: 'QA' },
  { value: 'eve', label: 'Eve 周', description: '运维', disabled: true },
];
</script>

<template>
  <CfMention
    v-model="text"
    :options="options"
    placeholder="输入 @ 触发提及"
  />
</template>

import { useState } from 'react';
import { CfMention } from '@chufix-design/react';

export default function Demo() {
const [text, setText] = useState('');
const options = [
  { value: 'alice', label: 'Alice Zhang', description: 'Frontend · Design System' },
  { value: 'bob', label: 'Bob Li', description: 'Backend · API Gateway' },
  // ...
];
return <CfMention value={text} onChange={setText} options={options} />;
}

Custom trigger character

trigger can be any single character. Pass # for tag selection, / for a command palette. Position and keyboard behavior are identical.

背景

<script setup lang="ts">
import { ref } from 'vue';
import { CfMention } from '@chufix-design/vue';

const text = ref('在评论里输入 # 试试');
const tags = [
  { value: 'bug', label: '#bug', description: '缺陷类问题' },
  { value: 'feature', label: '#feature', description: '新功能' },
  { value: 'question', label: '#question', description: '提问 / 讨论' },
  { value: 'docs', label: '#docs', description: '文档变更' },
];
</script>

<template>
  <CfMention
    v-model="text"
    trigger="#"
    :options="tags"
    placeholder="输入 # 选择标签"
  />
</template>

<CfMention
value={text}
onChange={setText}
trigger="#"
options={tags}
placeholder="Type # to pick a tag"
/>

Read-only / disabled

readonly keeps the display but blocks typing in the textarea; disabled grays it out and removes focus. The candidate dropdown will not appear in either mode.

背景

readonly

@alice 这条只读的评论给你看一眼。

disabled

<script setup lang="ts">
import { CfMention } from '@chufix-design/vue';

const sample = '@alice 这条只读的评论给你看一眼。';
const options = [
  { value: 'alice', label: 'Alice 张' },
  { value: 'bob', label: 'Bob 李' },
];
</script>

<template>
  <div style="display:flex; flex-direction:column; gap: 12px;">
    <div>
      <div style="font-size: 12px; color: var(--fg-3); margin-bottom: 4px;">readonly</div>
      <CfMention :model-value="sample" :options="options" readonly :rows="2" />
    </div>
    <div>
      <div style="font-size: 12px; color: var(--fg-3); margin-bottom: 4px;">disabled</div>
      <CfMention :model-value="sample" :options="options" disabled :rows="2" />
    </div>
  </div>
</template>

<CfMention value={sample} options={options} readonly />
<CfMention value={sample} options={options} disabled />

Keyboard interaction

While the dropdown is open, the following keys are supported:

Key	Behavior
`↑` / `↓`	Move the highlight between candidates
`Enter` / `Tab`	Select the highlighted candidate
`Esc`	Close the dropdown without inserting
Printable chars	Live-filter candidates
Space	Auto-closes the dropdown (treated as end of mention)

disabled items cannot be selected by keyboard and mouse clicks on them are ignored.

API

Prop	Type	Default	Description
`modelValue` (Vue) / `value` (React)	`string`	`''`	Text content
`defaultValue`	`string`	`''`	Uncontrolled initial value
`options`	`MentionOption[]`	`—`	`{ value, label?, description?, disabled? }`
`trigger`	`string`	`'@'`	Trigger character (single character)
`rows`	`number`	`4`	Textarea rows
`placeholder`	`string`	`'Type @ to mention'`	Textarea placeholder
`disabled` / `readonly`	`boolean`	`false`	Disable / read-only the editor
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Font size
`className`	`string`	`—`	Forwarded to the root container

Events:

onChange(value) / update:modelValue — any text change
onSelect(option) / select — fires when a candidate is selected

Type exports:

interface MentionOption {
  value: string;
  label?: string;
  description?: string;
  disabled?: boolean;
}