v3.1.0

Added

• Dynamic textStyle support: textStyle in trigger config now accepts a function that receives part data, allowing for dynamic styling based on mention content (#135, thanks to @juandjara, #134, #124)

Documentation

• Comprehensive documentation overhaul: Improved README clarity, added migration guides, and enhanced API documentation to better support developers transitioning to v3

Community

• Special thanks to @juandjara for contributing the dynamic textStyle feature in PR #135

---

This release maintains full backward compatibility while adding powerful new dynamic styling capabilities contributed by the community. The textStyle property can now be either a static style object or a function that receives the part data, enabling conditional styling based on mention content.

v3.0.0

Release Notes v3.0.0

About This Release

v3.0.0 represents a complete architectural overhaul of react-native-controlled-mentions. The library has been redesigned from the ground up with a focus on flexibility, performance, and developer experience. The core logic for rendering mentions, suggestions, and parsing mention values has been completely rethought.

The most significant change is the deprecating of the MentionInput component in favor of a powerful useMentions hook that provides full control over suggestion rendering while working directly with React Native's TextInput component.

🚀 Major New Features

New useMentions Hook

• Complete control: Hook-based architecture allows for full customization of suggestion rendering (#40, #44, #65, #75)
• Flexible integration: Works directly with the native TextInput component without wrapper components
• Better performance: Optimized rendering and state management

Advanced Trigger Support

• Multiple character triggers: Support for multi-character triggers like @@, ## (#38, #51)
• Custom regex patterns: Ability to provide custom regex patterns (e.g., david:123) (#52, #70, #80)
• Custom trigger patterns: Support for complex mention patterns beyond simple @ symbols

🛠️ API Changes

New Hook API

const { textInputProps, triggers } = useMentions({
  value: textValue,
  onChange: setTextValue,
  triggersConfig,
  onSelectionChange: handleSelectionChange, // NEW in Alpha.3
});

New Return Values

• mentionState: Access to internal mention parsing state
• Enhanced triggers object with better type safety

New Exports

• generateValueFromPartsAndChangedText: Utility for custom text generation
• triggerRegEx and singleGroupTriggerRegEx: Regex utilities for pattern matching

🔧 Breaking Changes

Component Architecture

• Deprecate MentionInput component: Use useMentions hook with TextInput instead
• Removed props: containerStyle, inputRef (use ref directly), renderSuggestions, isBottomMentionSuggestionsRender

Naming Conventions

The following names have been updated for better clarity:

// OLD → NEW
MentionSuggestionsProps → SuggestionsProvidedProps
onSuggestionPress → onSelect
PartType → Config
isTriggerPartType → isTriggerConfig
getMentionValue → getTriggerValue
replaceMentionValues → replaceTriggerValues

Mention Format Changes

• Default format: Changed from @[David Tabaka](123) to {@}[David Tabaka](123)
• Regex groups: Custom regex patterns must now have only one regex group
• Trigger wrapping: Triggers are now wrapped in {} to support multi-character triggers

🐛 Bug Fixes

• Emoji stability: Fixed unstable behavior with typed emojis in TextInput (#66)
• Selection handling: Enhanced text selection and cursor positioning

📖 Documentation & Examples

• Updated README: Comprehensive documentation for the new hook-based approach
• More examples: Added examples for various use cases
  • Functional components with filtering (#47)
  • Triggerable button integration (#67)
  • Advanced configuration patterns
• Better formatting: Improved code examples and API documentation

🧪 Testing & Quality

• Enhanced test coverage: Added tests for patternsConfig and trigger functionality
• Code improvements: Simplified conditions and improved readability in core helpers
• Type safety: Better TypeScript support throughout the library

📦 Installation

# Install the stable release
npm install react-native-controlled-mentions
# or
yarn add react-native-controlled-mentions

🔄 Migration Guide

From v2.x to v3.0.0

1. Replace MentionInput with useMentions hook:

// OLD v2.x
<MentionInput
  value={value}
  onChange={setValue}
  partTypes={partTypes}
  renderSuggestions={renderSuggestions}
/>

// NEW v3.0.0
const { textInputProps, triggers } = useMentions({
  value,
  onChange: setValue,
  triggersConfig,
});

return (
  <>
    <YourSuggestions {...triggers.mention} />
    <TextInput {...textInputProps} />
  </>
);

2. Update configuration format:

// OLD
const partTypes = [
  {
    trigger: '@',
    textStyle: { fontWeight: 'bold' },
  },
];

// NEW
const triggersConfig = {
  mention: {
    trigger: '@',
    textStyle: { fontWeight: 'bold' },
  },
};

3. Update mention format in stored data:
   • Change @[Name](id) to {@}[Name](id) in existing data

🤝 Community

This release incorporates feedback and contributions from the community. Special thanks to all contributors who helped shape this major release through issues, discussions, and testing of alpha versions.

For detailed migration assistance and examples, please visit the documentation and check out the example directory.

Big Update Comming! v3.0.0-alpha.2 Pre-release Notes

About Release

In that release was rethought and re-designed logic for rendering mentions, suggestions and core logic for parsing mention values. In fact, we have no need to render all this stuff in the MentionInput component. And more – we don't need the MentionInput component as well. It's enough to provide just a few props directly to the TextInput component.

Now you will be able to use hook for control mention state. The main idea – suggestions rendering now will be fully controlled by user and is extracted from MentionInput component.

Added

• New useMentions hook that allows to render suggestions separately from TextInput component (#40, #44, #65, #75)
• Ability to provide custom regex pattern (for example, david:123. #52, #70, #80)
• Ability to use multiple characters triggers (for example @@, ## etc. #38, #51)
• More examples for different cases (#67)

Fixed

• Some unstable behavior with typed emojis in the TextInput (#66)

Breaking Changes

• Change default trigger regex and mention value from @[David Tabaka](123) to {@}[David Tabaka](123)
• Now custom regex patterns should have only one regex group
• Removed containerStyle prop from the MentionInput component
• Removed inputRef prop from the MentionInput component, use traditional ref now
• Removed renderSuggestions and isBottomMentionSuggestionsRender from the PartType (new Config type)
• Some refactored names:

MentionSuggestionsProps -> SuggestionsProvidedProps
onSuggestionPress -> onSelect
PartType -> Config
isTriggerPartType -> isTriggerConfig
getMentionValue -> getTriggerValue
replaceMentionValues -> replaceTriggerValues

How To Play

To play with this alpha pre-release, please switch to this branch for docs and examples. Also, you can install alpha version using next commands:

yarn add react-native-controlled-mentions@alpha
// or
npm install --save react-native-controlled-mentions@alpha

v2.2.4

FIXED

• Error when value is null (#36)
• Errors with regex named capture groups on iOS < 12 (#23) and Hermes (#37)
• Wrong behavior on adding ) after mention part (#24)
• Wrong behavior on adding emails (#41)

v2.2.0

ADDED

• Ability to show mention suggestions for keywords with spaces (#25)

v2.1.0

ADDED

• Ability to render mention suggestions at the bottom of text input (#27)

v2.0.0

Styling for custom patterns support

ADDED

• partTypes property for defining a list of possible mention or pattern types for parsing (e. g. URLs) (#13)

BREAKING CHANGES

• mentionTypes renamed to partTypes
• MentionType changed to PartType which can be either MentionPartType or PatternPartType

New types defined in README.md.

v1.0.0

Hashtag support

BREAKING CHANGES

• renderSuggestions, trigger, isInsertSpaceAfterMention, mentionTextStyle is now moved to mentionTypes property
• 'Mentions' component now renamed to 'MentionInput'
• mentionRegEx changed a little big

Please see the example app in /example folder to get more details.

FIXED

• Wrong editing with keyboard auto-correction (#1)

ADDED

• Support for multiple mention types (#9)
• Jest tests support

v0.1.8

Fixed bugs:

• inputRef undefined for Mentions #11

v0.1.7

New

• add mentionTextStyle property (#9)
• enchanted mention regex to accept word characters and "-" (#9)

Fixed

• bug with adding mention on new line (#10)