Mentions

mentions

Suggests and inserts mention tokens while the user types structured text.

Usage

Basic usage

Enter @ to evoke the candidate floating layer, select with the arrow keys, and insert mention by Enter/Tab.

tsx

<Mentions
  options={people}
  placeholder="Enter @ to mention a colleague..."
  onChange={setValue}
  onSelect={(o) => console.log(o)}
/>

Custom trigger

prefix is changed to "#" to associate non-personnel entities such as work orders.

tsx

<Mentions
  prefix="#"
  options={tickets}
  placeholder="Enter # associated work order..."
/>

Invalid state

invalid is marked with a red border and lacks mention in conjunction with the form verification prompt.

tsx

<Mentions options={people} invalid defaultValue="Missing @person in charge" />

Disabled

disabled Editing is prohibited, and the submitted mention will still be displayed in color.

tsx

<Mentions options={people} disabled defaultValue="Disabled @Lin Xiao" />

When to use

Use Mentions when free-form multiline text needs inline references, such as mentioning a person with @ or linking a ticket with #. It behaves like a Textarea until a configured trigger opens the suggestion popup. Unlike Combobox, which selects the field's entire value, Mentions inserts references into otherwise ordinary text.

Import

import { Mentions, MentionText, type MentionTextProps, findTrigger, insertMention, defaultFilter, segmentMentions, type MentionSegment } from "@hulianui/ui"

Props

Name	Type	Default	Description
options*	`MentionOption[]`	—	Suggestions containing `value` and `label`, with optional `description`, `startContent`, and `disabled`.
value	`string`	—	Controlled text value; pair with `onChange`.
defaultValue	`string`	—	Initial text when uncontrolled.
prefix	`string`	`"@"`	Trigger, including multi-character values such as `"@@"` or `"#"`. Suggestions open only at the start of a line or after whitespace.
filter	`false \| ((option, query) => boolean)`	Built-in substring match	Pass `false` to disable local filtering and use `onSearch`, or pass a function for custom filtering. The default matches `label` and `value` case-insensitively.
size	`"sm" \| "md" \| "lg"`	`"md"`	Textarea visual size.
invalid	`boolean`	`false`	Applies invalid styling when used outside Field.
placeholder	`string`	—	Placeholder passed to the textarea.
rows	`number`	`3`	Row count passed to the textarea.
disabled	`boolean`	`false`	Disables the input.
className	`string`	—	Additional class name for the field container.
popupClassName	`string`	—	Additional class name for the suggestion popup.

Also accepts native Textarea attributes except size, value, defaultValue, onChange, onSelect, and prefix, which use the component-specific contracts above.

Events

Event	Type	Description
onChange	`(value: string) => void`	Called when text changes; required when controlled.
onSearch	`(query: string) => void`	Reports query changes for external or asynchronous filtering; it does not return results.
onSelect	`(option: MentionOption) => void`	Called with the complete selected option.

Example

tsx

<Mentions
  options={people}
  defaultValue="Please ask "
  placeholder="Type @ to mention a colleague…"
  onSelect={(o) => console.log(o)}
/>

Use # to reference a ticket:

tsx

<Mentions prefix="#" options={tickets} placeholder="Type # to link a ticket…" />

Usage guidelines

Pair a controlled value with onChange; otherwise the field is read-only, just like a native controlled textarea.
Inserted text is prefix + label + " "; label is both the visible name and the literal stored in the text. Use onSelect to handle cases where display and stored values must differ.
For external or asynchronous filtering, set filter={false} and refresh options from onSearch; otherwise the built-in substring filter will filter the consumer's results a second time.
The suggestions listbox accessible name reads ConfigProvider's locale.components.mentions.suggestions. zhCN and enUS include it; legacy custom locales that omit this optional field retain the Chinese fallback.

SecretField · Combobox · Listbox · InputOTP · Rating · Upload

Playground

TriggersizePlaceholderrowsinvaliddisabled

<Mentions
  prefix="@"
  size="md"
  options={people}
  placeholder="Enter @ to mention a colleague..."
  rows={3}
  onChange={setValue}
  onSelect={(o) => console.log(o)}
/>

Usage

Basic usage

Enter @ to evoke the candidate floating layer, select with the arrow keys, and insert mention by Enter/Tab.

tsx

<Mentions
  options={people}
  placeholder="Enter @ to mention a colleague..."
  onChange={setValue}
  onSelect={(o) => console.log(o)}
/>

Custom trigger

prefix is changed to "#" to associate non-personnel entities such as work orders.

tsx

<Mentions
  prefix="#"
  options={tickets}
  placeholder="Enter # associated work order..."
/>

Invalid state

invalid is marked with a red border and lacks mention in conjunction with the form verification prompt.

tsx

<Mentions options={people} invalid defaultValue="Missing @person in charge" />

Disabled

disabled Editing is prohibited, and the submitted mention will still be displayed in color.

tsx

<Mentions options={people} disabled defaultValue="Disabled @Lin Xiao" />

When to use

Props

Name	Type	Default	Description
options*	`MentionOption[]`	—	Suggestions containing `value` and `label`, with optional `description`, `startContent`, and `disabled`.
value	`string`	—	Controlled text value; pair with `onChange`.
defaultValue	`string`	—	Initial text when uncontrolled.
prefix	`string`	`"@"`	Trigger, including multi-character values such as `"@@"` or `"#"`. Suggestions open only at the start of a line or after whitespace.
filter	`false \| ((option, query) => boolean)`	Built-in substring match	Pass `false` to disable local filtering and use `onSearch`, or pass a function for custom filtering. The default matches `label` and `value` case-insensitively.
size	`"sm" \| "md" \| "lg"`	`"md"`	Textarea visual size.
invalid	`boolean`	`false`	Applies invalid styling when used outside Field.
placeholder	`string`	—	Placeholder passed to the textarea.
rows	`number`	`3`	Row count passed to the textarea.
disabled	`boolean`	`false`	Disables the input.
className	`string`	—	Additional class name for the field container.
popupClassName	`string`	—	Additional class name for the suggestion popup.

Also accepts native Textarea attributes except size, value, defaultValue, onChange, onSelect, and prefix, which use the component-specific contracts above.

Events

Event	Type	Description
onChange	`(value: string) => void`	Called when text changes; required when controlled.
onSearch	`(query: string) => void`	Reports query changes for external or asynchronous filtering; it does not return results.
onSelect	`(option: MentionOption) => void`	Called with the complete selected option.

Usage guidelines

Pair a controlled value with onChange; otherwise the field is read-only, just like a native controlled textarea.

Inserted text is prefix + label + " "; label is both the visible name and the literal stored in the text. Use onSelect to handle cases where display and stored values must differ.

For external or asynchronous filtering, set filter={false} and refresh options from onSearch; otherwise the built-in substring filter will filter the consumer's results a second time.

The suggestions listbox accessible name reads ConfigProvider's locale.components.mentions.suggestions. zhCN and enUS include it; legacy custom locales that omit this optional field retain the Chinese fallback.

Mentions

Usage

Basic usage

Custom trigger

Invalid state

Disabled

When to use

Import

Props

Events

Example

Usage guidelines

Related

Playground

Mentions

Usage

Basic usage

Custom trigger

Invalid state

Disabled

When to use

Import

Props

Events

Example

Usage guidelines

Related

Playground