react-native-mentions-input

A flexible mentions input component for React Native. Supports @mentions, #hashtags, or any custom trigger character.

Features

• Customizable trigger character (@, #, or any string)
• Controlled component pattern for full state control
• Three deletion modes for different UX behaviors
• Read-only MentionsText for displaying saved content
• TypeScript support with generics for custom mention data
• Works on iOS, Android, and Web

Installation

npm install react-native-mentions-input
# or
yarn add react-native-mentions-input
Copy

Quick Start

import { useState } from 'react';
import { MentionsInput, type Mention } from 'react-native-mentions-input';

function MyInput() {
  const [text, setText] = useState('');
  const [mentions, setMentions] = useState<Mention[]>([]);

  return (
    <MentionsInput
      value={text}
      onChangeText={setText}
      mentions={mentions}
      onMentionsChange={setMentions}
      renderSuggestions={({ query, onSelect }) => (
        <MySuggestionsList query={query} onSelect={onSelect} />
      )}
    />
  );
}
Copy

Core Concepts

Controlled State

The component uses a controlled pattern. You manage two pieces of state:

• value - The text string
• mentions - Array of mention objects with position tracking

type Mention<T = unknown> = {
  id: string | number;
  start: number;      // Position in text (inclusive)
  end: number;        // Position in text (exclusive)
  displayText: string;
  data?: T;           // Your custom data
};
Copy

Rendering Suggestions

You provide a renderSuggestions function that receives:

type SuggestionRenderProps<T> = {
  query: string;                              // Text after trigger (e.g., "joh" for "@joh")
  onSelect: (suggestion: MentionSuggestion<T>) => void;
  onDismiss: () => void;
};
Copy

When the user selects a suggestion, call onSelect with:

onSelect({
  id: user.id,
  displayText: user.name,  // Will appear as "@John Doe"
  data: user,              // Optional custom data
});
Copy

Delete Modes

Control what happens when users edit within a mention:

Mode	Behavior
'default'	Mention is removed, modified text remains
'whole'	Entire mention text is deleted
'requery'	Triggers new search with remaining text

<MentionsInput deleteMode="whole" ... />
Copy

API Reference

Full API documentation is available at atomic-solutions.github.io/react-native-mentions-input

Components

• MentionsInput - TextInput with mention detection
• MentionsText - Read-only text with highlighted mentions

Hooks

For custom implementations:

• useMentionsInput - Core mention detection logic
• useMentionInsertion - Mention insertion at cursor

Utilities

• findWordCoordsAt - Find word boundaries at cursor
• validateMentions - Filter invalid mentions
• getUpdatedMentions - Recalculate positions after edits

Examples

Custom Trigger (Hashtags)

<MentionsInput
  trigger="#"
  value={text}
  onChangeText={setText}
  mentions={hashtags}
  onMentionsChange={setHashtags}
  renderSuggestions={({ query, onSelect }) => (
    <HashtagSuggestions query={query} onSelect={onSelect} />
  )}
/>
Copy

Displaying Saved Content

import { MentionsText } from 'react-native-mentions-input';

<MentionsText
  value={savedText}
  mentions={savedMentions}
  mentionStyle={{ color: '#1a73e8', fontWeight: '600' }}
/>
Copy

With TypeScript Generics

type User = { id: number; name: string; avatar: string };

const [mentions, setMentions] = useState<Mention<User>[]>([]);

<MentionsInput<User>
  mentions={mentions}
  onMentionsChange={setMentions}
  // ...
/>
Copy

Running the Example App

yarn install
yarn example start
Copy

Contributing

See CONTRIBUTING.md for development workflow and guidelines.

License

MIT