npm version CI npm bundle size TypeScript React Context7 Ask DeepWiki

A React component that enables Facebook/Twitter-style @mentions and tagging in textarea inputs with full TypeScript support.

• ✅ Flexible Triggers - Use any character or pattern to trigger mentions (@, #, :, or custom)
• 🎨 Tailwind v4 Ready - First-class support for Tailwind CSS v4 utility styling
• ⚡ Async Data Loading - Load suggestions dynamically from APIs
• 🔍 Smart Suggestions - Real-time filtering and matching
• ♿ Accessible - Built with ARIA labels and keyboard navigation
• 🎯 TypeScript First - Written in TypeScript with complete type definitions
• 🧪 Well Tested - Comprehensive test suite with Testing Library
• 🌐 SSR Compatible - Works with Next.js and other SSR frameworks
• 📱 Mobile Friendly - Touch-optimized for mobile devices

# npm
npm install react-mentions-ts --save
# yarn
yarn add react-mentions-ts
# pnpm
pnpm add react-mentions-ts

React Mentions TS uses peer dependencies for its styling helpers and React runtime. Ensure these are installed in your application (skip any you already have):

# npm
npm install class-variance-authority clsx react react-dom tailwind-merge
# yarn
yarn add class-variance-authority clsx react react-dom tailwind-merge
# pnpm
pnpm add class-variance-authority clsx react react-dom tailwind-merge

Check package.json for the latest peer dependency version ranges.

import { useState } from 'react'
import { MentionsInput, Mention } from 'react-mentions-ts'
function MyComponent() {
 const [value, setValue] = useState('')
 return (
 <MentionsInput value={value} onMentionsChange={({ value: nextValue }) => setValue(nextValue)}>
 <Mention trigger="@" data={users} renderSuggestion={(entry) => <div>{entry.display}</div>} />
 <Mention trigger="#" data={tags} />
 </MentionsInput>
 )
}

@import "tailwindcss";
(...)
@import "react-mentions-ts/styles/tailwind.css";

MentionsInput is the main component that renders the textarea control. It accepts one or multiple Mention components as children. Each Mention component represents a data source for a specific class of mentionable objects:

• 👥 Users - @username mentions
• 🏷️ Tags - #hashtag mentions
• 📋 Templates - {{variable}} mentions
• 🎭 Emojis - :emoji: mentions
• ✨ Custom - Any pattern you need!

View more examples

The MentionsInput component supports the following props:

onMentionsChange receives an object with the following fields:

• value: the latest markup string containing mentions
• plainTextValue: the same content without mention markup
• mentions: the mention occurrences extracted from the new value
• previousValue: the markup string before the change
• trigger: metadata about what caused the change. trigger.type is one of 'input', 'paste', 'cut', 'mention-add', or 'mention-remove', and, when available, trigger.nativeEvent references the originating DOM event (optional; do not rely on its exact shape). Regular text edits (typing, Backspace/Delete) use trigger.type: 'input'.

Each data source is configured using a Mention component, which has the following props:

Need the legacy markup customization? Import createMarkupSerializer from react-mentions and pass markup={createMarkupSerializer(':__id__')} (or any other template) to keep markup/parse logic in sync without wiring a regex manually.

If a function is passed as the data prop, it receives the current search query and should return a promise that resolves with the list of suggestions.

type User = { id: string; display: string }
const fetchUsers = async (query: string): Promise<User[]> => {
 const response = await fetch(`/api/users?search=${query}`)
 return response.json()
}
<Mention trigger="@" data={fetchUsers} />

React Mentions ships its markup with Tailwind utility classes. Consumers should have Tailwind configured in their application build so these classes compile to real CSS. If you do not use Tailwind you can still provide your own styles via className, CSS modules, or inline styles.

The components assume Tailwind is available in the consuming app. A minimal setup looks like:

// tailwind.config.js
module.exports = {
 content: ['./src/**/*.{js,ts,jsx,tsx}'],
 theme: { extend: {} },
 plugins: [],
}

/* src/index.css (or your global stylesheet) */
@import "tailwindcss";
@import "react-mentions-ts/styles/tailwind.css";

The optional helper react-mentions-ts/styles/tailwind.css only declares an @source "../dist"; directive so Tailwind v4 can detect the library's utility classes inside node_modules/react-mentions-ts/dist. Including it keeps your Tailwind config clean and avoids adding explicit content globs for the package.

If you are still on Tailwind v3, add ./node_modules/react-mentions-ts/dist/**/*.{js,jsx,ts,tsx} to the content array instead of importing the helper file.

<MentionsInput style={customStyle}>
 <Mention style={mentionStyle} />
</MentionsInput>

When suggestionsDisplay="inline", override the inlineSuggestion style slot to customize the inline hint (the default demo style lives in demo/src/examples/defaultStyle.ts).

See demo/src/examples/defaultStyle.ts for examples.

Simply assign a className prop to MentionsInput. All DOM nodes will receive derived class names:

<MentionsInput className="mentions">
 <Mention className="mentions__mention" />
</MentionsInput>

Due to React Mentions' internal cursor tracking, use @testing-library/user-event for realistic event simulation:

import { render } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
test('mentions work correctly', async () => {
 const user = userEvent.setup()
 const { getByRole } = render(<MyMentionsComponent />)
 await user.type(getByRole('textbox'), '@john')
 // assertions...
})

• Contributions are welcome! If you want to contribute, first of all: thank you! ❤️
• Please check out our Contributing Guide for guidelines about how to proceed.
• React Mentions is licensed under the BSD-3-Clause License.

This project is a TypeScript rewrite and modernization of the original react-mentions library.

Made with contrib.rocks.