Mentions
Capture @-mentions in a textarea with a markup value and suggestions dropdown
Source
Package
Usage
Mentions is a textarea that opens a suggestions dropdown when the user types a trigger character,
for example @ or #. Picking a suggestion inserts a mention. Deleting any part of a mention
removes the whole mention:
Value and markup
Mentions value is a markup string: each mention is stored as @[__display__](__id__),
while the user sees only the display text. For example, the value:
is displayed as Hey Walter White, are you there?.
By default, the trigger character is not displayed. Set withTrigger on Mentions.Mention
to display the same value as Hey @Walter White, are you there?:
Custom mention rendering
Use renderMention prop to customize how mentions are displayed, for example to add
a tooltip. The returned content must take the same space as the mention text, otherwise
mentions are misaligned with the input text:
Custom suggestions
Use renderSuggestion on Mentions.Mention to customize suggestions in the dropdown:
onChange payload
Unlike other Mantine inputs, Mentions onChange is called with an object instead of a string:
payload.reason.type is one of:
'input'– regular typing or deletion that does not remove a mention'mention-add'– a suggestion was inserted (payload.mentionIdis set)'mention-remove'– an edit removed one or more mentions'paste'– text was pasted'cut'– a selection was cut'insert-text'– text was dragged and dropped into the field'undo'and'redo'– the change came from the undo history
Mentions with uncontrolled forms
Set name to submit the markup string, including mention IDs, rather than the displayed text:
Usage with form
Mentions onChange receives a payload object, so form.getInputProps alone does not store
the markup string. Spread getInputProps for error and onBlur, then set value and
onChange yourself:
onAdd
onAdd on Mentions.Mention is called when a suggestion is inserted. startPos and endPos
are positions in the text the user sees, not in the markup value:
Copy and paste
Mentions are kept when text is copied or cut and then pasted into a Mentions field
with the same triggers. Other applications receive plain text.
Multiple triggers
Add one Mentions.Mention for each trigger. The markup starts with the trigger: mentions
of the # source below are stored as #[__display__](__id__):
RegExp triggers
trigger also accepts a RegExp, for example to open the dropdown on both @ and +.
Mentions of a RegExp trigger are stored as @[__display__](__id__), use markup prop
to change that:
To control how the query is matched, use a RegExp with two capture groups anchored with $:
group 1 captures the trigger with the query, group 2 the query.
Data sources
data prop of Mentions.Mention accepts an array of { id, display } items or a function
that returns matches. Array data is filtered by the query, case-insensitively.
- Set
ignoreAccentsto matchJoséwithjose - Set
allowSpaceInQueryto allow spaces in the query, by default the query ends at the first whitespace
Custom filter
Use filter prop to change how array data is filtered. Set filter={false} to display
the data as is, for example when it is already filtered on the server:
maxSuggestions
Set maxSuggestions on Mentions.Mention to limit the number of displayed suggestions:
Virtualized dropdown
Use virtualizer to render only the visible suggestions in the overlay. Type @ to browse 5,000 members:
Async data
data function can be asynchronous. It receives the query and an AbortSignal that is
aborted when the request becomes stale. Use debounceMs to debounce requests:
Loading, empty and error states
Use loadingMessage, errorMessage and nothingFoundMessage props to change messages
displayed in the dropdown. To change them for a single source, use renderEmpty and
renderError on Mentions.Mention:
Custom markup
Use markup prop of Mentions.Mention to change how mentions are stored, for example
{{__id__}}. If the format cannot be described with a template, pass a serializer object
with insert and findAll methods. Use a serializer when id can contain ) or
display can contain ](.
displayTransform
displayTransform on Mentions.Mention changes the displayed text of mentions without
changing the value, for example to display only the first name:
Mention styles
Set className and style on Mentions.Mention to style mentions of a single source:
To style mentions of all sources, use the highlight Styles API selector or the
--mentions-highlight-color and --mentions-highlight-bg CSS variables.
Anchor mode
By default, the dropdown is displayed below the caret. Set anchorMode="left" to align it
with the left edge of the input. Set suggestionsPlacement="above" to display it above the
input or "auto" to pick the side with more space.
Inline suggestions
Set suggestionsDisplay="inline" to display the first match as ghost text at the caret
instead of the dropdown. Press Tab or Enter to accept it:
Type @ then press Tab, Enter or → to accept the suggestion
Caret-aware styling
Use data-mention-selection attribute to style mentions based on the caret position:
inside, boundary, partial or full. onSelectionChange is called with the current
selection and the mentions it overlaps:
Parsing mentions
Use getMentions function to get mentions from a markup value, for example on submit:
createMarkupSerializer builds a serializer from a template string, makeTriggerRegex
builds a trigger RegExp.
Undo and redo
Mentions keeps its own undo history: undo and redo shortcuts restore removed mentions.
External changes of a controlled value, for example a form reset, can be undone as well.
Single line
Set singleLine to render an input instead of a textarea:
Disabled and static
Set disabled to disable the input. Set mode="static" to display a value with mentions
that cannot be edited:
Accessibility
Give the input a visible label. Use a11ySuggestionsListLabel to name the suggestions list:
Keyboard interactions
Keyboard interactions while the suggestions dropdown is open:
- ArrowDown / ArrowUp – highlight the next/previous suggestion
- Enter / Tab – insert the highlighted suggestion
- Escape – close the dropdown. Inside
ModalorDrawer, the first Escape closes the dropdown only
Keyboard interactions with suggestionsDisplay="inline" while the ghost text is visible:
- Tab / Enter – accept the suggestion
- → – accept the suggestion when the caret is at the end of the text
- Escape – dismiss the suggestion
Styles API
Styles API
Mentions supports the Styles API; you can add styles to any inner element of the component with the classNames prop. Follow the Styles API documentation to learn more.
Description
Component Styles API
Hover or focus a selector to highlight its elements