@rc-component/mentions

_{Part of the Ant Design ecosystem.}

💬 React mentions textarea with searchable suggestions and keyboard navigation.

English | 简体中文

Highlights

• Textarea mentions with prefix based search and selection.
• Keyboard navigation for suggestion menus.
• Data-driven options API and Option children API.
• Multiple prefixes, custom filtering, custom validation, and split token support.
• Built on @rc-component/input, @rc-component/menu, and @rc-component/trigger.

Install

npm install @rc-component/mentions

The package is published as @rc-component/mentions. Legacy rc-mentions references should migrate to the scoped package name.

Usage

import Mentions from '@rc-component/mentions';

const options = [
  { value: 'light', label: 'Light' },
  { value: 'bamboo', label: 'Bamboo' },
  { value: 'cat', label: 'Cat' },
];

export default () => (
  <Mentions options={options} placeholder="Use @ to mention someone" />
);

import Mentions from '@rc-component/mentions';

const { Option } = Mentions;

export default () => (
  <Mentions prefix={['@', '#']}>
    <Option value="design">Design</Option>
    <Option value="docs">Docs</Option>
  </Mentions>
);

Import the styles from assets/index.less or the compiled CSS generated by npm run compile.

Examples

Run the local dumi site:

npm install
npm start

Then open http://localhost:8000.

API

Mentions

Property	Type	Default	Description
allowClear	boolean | AllowClearConfig	false	Show a clear button for the textarea value.
autoFocus	boolean	false	Focus the textarea when mounted.
autoSize	boolean | { minRows?: number; maxRows?: number }	-	Auto resize textarea height.
children	ReactNode	-	Mentions.Option children.
className	string	-	Class name for the root element.
classNames	MentionsProps['classNames']	-	Semantic class names for slots.
defaultValue	string	-	Initial value.
direction	'ltr' | 'rtl'	ltr	Popup direction.
filterOption	false | (input: string, option: OptionProps) => boolean	-	Customize option filtering.
getPopupContainer	() => HTMLElement	-	Container for the suggestion popup.
id	string	-	Textarea id.
notFoundContent	ReactNode	Not Found	Content shown when no option matches.
options	DataDrivenOptionProps[]	-	Data-driven options.
placement	'top' | 'bottom'	bottom	Suggestion popup placement.
popupClassName	string	-	Class name for the popup.
prefix	string | string[]	@	Trigger prefix or prefixes.
prefixCls	string	rc-mentions	Class name prefix.
rows	number	1	Textarea row count.
silent	boolean	false	Ignore Enter behavior during transition phases.
split	string	' '	String inserted after a selected mention.
style	React.CSSProperties	-	Inline styles for the root element.
styles	MentionsProps['styles']	-	Semantic styles for slots.
transitionName	string	-	Popup transition name.
validateSearch	(text: string, split: MentionsProps['split']) => boolean	-	Customize trigger search logic.
value	string	-	Controlled value.
onBlur	React.FocusEventHandler<HTMLTextAreaElement>	-	Triggered when textarea loses focus.
onChange	(text: string) => void	-	Triggered when value changes.
onFocus	React.FocusEventHandler<HTMLTextAreaElement>	-	Triggered when textarea receives focus.
onKeyDown	React.KeyboardEventHandler<HTMLTextAreaElement>	-	Triggered on key down.
onKeyUp	React.KeyboardEventHandler<HTMLTextAreaElement>	-	Triggered on key up.
onPopupScroll	(event: React.UIEvent<HTMLDivElement>) => void	-	Triggered when the popup scrolls.
onPressEnter	React.KeyboardEventHandler<HTMLTextAreaElement>	-	Triggered when Enter is pressed.
onResize	(size: { width: number; height: number }) => void	-	Triggered when textarea size changes.
onSearch	(text: string, prefix: string) => void	-	Triggered when a prefix starts a search.
onSelect	(option: OptionProps, prefix: string) => void	-	Triggered when an option is selected.
popupRender	(menu: React.ReactElement) => ReactNode	-	Customize the dropdown menu rendering

Option

Property	Type	Default	Description
children	ReactNode	-	Option label.
className	string	-	Class name for the option.
disabled	boolean	false	Disable the option.
key	string	-	React key and option key.
style	React.CSSProperties	-	Inline option style.
value	string	-	Mention value inserted into the textarea.

Ref

import Mentions, { type MentionsRef } from '@rc-component/mentions';

const ref = React.useRef<MentionsRef>(null);

ref.current?.focus();
ref.current?.blur();

Property	Type	Description
focus	() => void	Focus the textarea.
blur	() => void	Blur the textarea.
textarea	HTMLTextAreaElement | null	Deprecated textarea reference.
nativeElement	HTMLElement	Root native element.

Development

npm install
npm start
npm test
npm run tsc
npm run compile
npm run build

The dumi site runs at http://localhost:8000 by default.

Release

npm run prepublishOnly

The release flow is handled by @rc-component/np through the rc-np command after the package build.

License

@rc-component/mentions is released under the MIT license.

Clear configuration

allowClear accepts a boolean or an AllowClearConfig object from @rc-component/util:

interface AllowClearConfig {
  clearIcon?: React.ReactNode;
  disabled?: boolean;
  tabIndex?: number;
  label?: string;
}

All fields are optional. disabled: true behaves like allowClear={false}: the clear button and space reserved solely for it are removed; the input remains editable. Existing suffixes and other content are preserved. This changes the previous hidden-button spacing behavior where applicable.

tabIndex affects only the clear button; -1 removes it from Tab navigation while retaining mouse activation. label supplies its accessible name through aria-label. Defaults, clear values, callbacks, and component state restrictions are unchanged.

When no other affix keeps the wrapper mounted, dynamically disabling clearing can recreate the input DOM node and lose focus or selection, just like switching to allowClear={false}. The value is preserved. With an existing suffix, the wrapper, focus, and selection remain stable.