README.md

react-native-mentionable-textinput

ReactNative TextInput with enhanced capabilities for mentions

Features

• Tag multiple items using different characters
• Live search across mentionable items
• Customizable textinput icons and style
• Search among words with spaces
• Detox-tested and works as a charm out of the box!
• Hook useMention available

Installation

yarn add react-native-mentionable-textinput
yarn add react-native-device-info
cd ios; pod install; cd ..

Showcase

sample.mov

Usage

import { TextInputMention } from "react-native-mentionable-textinput";

// ...

<TextInputMention
    mentionsTypes={[
      {
        type: 'users',
        mentionChar: '@',
      },
      {
        type: 'channels',
        mentionChar: '#',
      },
    ]}
    onSend={onSubmit}
    searchMentionableItems={searchItems}
    mentionableItems={itemsFound}
    submitIcon={<Image style={iconStyle} source={{ uri: send }} />}
    mentionIcon={<Image style={iconStyle} source={{ uri: email }} />}
    closeIcon={<Image style={iconStyle} source={{ uri: close }} />}
    maxHeightMentionWindow={200}
  />

Component props

Name	Type	Mandatory	Additional info
mentionsTypes	Array	✔️	Type of objects that can be mentioned
initialText	string	❌	Initial text of the text input
placeholder	string	❌	Text input placeholder
initialMentioned	Array	❌	Every mention is contained in this array. Fill it with inital mention elements
isMentionsDisabled	boolean	❌	False if text input should not have mentions
isSendButtonDisabled	boolean	❌	True if text input submit button is disable.
isSmartSearchEnabled	boolean	❌	True if smart search should be enabled
children	Array<JSX.Element>	❌	Optional view that will be attached above text input
mentionableItems	Array	✔️	List of visible items that can be mentioned
searchMentionableItems	(mentionType: string, searchText: string) => void	✔️	Search callback to filter mentionable items
onChangeText	(text: string, mentioned: Array) => void	❌	Callback passed to text input
onMentionClose	() => void	❌	Callback when the list of mentionable items is closed
onSend	(text: string, mentioned: Array)	✔️	Called on submit
onEndTyping	() => void	❌	Callback passed to text input
textStyle	StyleProp	❌	Style of text, excluded mentions
mentionStyle	StyleProp	❌	Style of mentions, included mention character
mentionContainerStyle	StyleProp	❌	Style of mentions container view
textInputContainerStyle	StyleProp	❌	Style of text input container
separatorColor	string	❌	Color of the separator between text input and mention window
submitIcon	JSX.Element	✔️	Icon for on submit action
mentionIcon	JSX.Element	✔️	Icon for mention
closeIcon	JSX.Element	✔️	Icon for close
textInputProps	TextInputProps	❌	Props for native TextInput
keyboardAvoidingViewProps	KeyboardAvoidingViewProps	❌	Props for native KeyboardAvoidingView
maxHeightMentionWindow	number	✔️	Max height of mentions container view
renderMentionType	(mentionType: string) => JSX.Element	❌	Custom render of mentionable items

Hooks properties

useMentions is born as a plugin to add mentions to a component that has the properties of text input. The following are needed:

• onChangeText
• onSelectionChange

The hook can be attached as a plugin to any component that accepts these props.

You can create with

  const hook = useMention({
    searchMentionableItems: mySearchFunction,
    mentionableItems: myResultsOfSearchMentionableItems
    onSend: mySendFunction,
    mentionsTypes: [
      {
        type: 'TYPE_1',
        mentionChar: '+',
      }
    ],
    mentionableItems: [
      {id: '1', label: 'First item label', type: 'TYPE_1'},
      ...
    ],
    ...
  });

and the following properties are available:

Name	Type	Additional info
mentioned	Array	List of mentioned items added
formattedText	string	Complete label to place into input text
onChangeText	(text: string, mentioned: Array<Mention>) => void	Callback when text changes, passed to TextInput
onSelectionChange	(event: { nativeEvent: { selection: CursorPosition } }) => void	Callback when text is selected, passed to TextInput
cursorPosition	{ start: number; end: number }	Position of the cursor
addMention	(mention: {id: string; label: string; type: T}) => void	Add a new mentioned item
chosenMentionType	string - type T	Type of the selected mention item
showMentionItems	boolean	Check if mention items should be visible
showMentionTypes	boolean	Check if mention types should be visible
isMentionsDisabled	boolean	Check if mention feature is enabled
onSendCallback	() => void	Calls onSend passed as props to the hook. Internally it uses onSend(inputText, mentioned)
onPressMentionIcon	() => void	Callback when mention icon is pressed
mentionableItems	Array<MentionListItem>	List of all mentionable items
onPressMentionType	(mentionType: T, localCursorPosition?: CursorPosition) => void	Prepares the hook to give you the data to show the mentions type
closeMention	() => void	Prepare the hook to close the mention popup
mentionItemsVisible	boolean	Check if showMentionItems with items list should be visible
isTextUpdated	boolean	Returns if text has changed wrt initial text
mentionsTypes	Array<MentionItemType>	List of mention types
isSmartSearchEnabled	boolean	True if smart search is active
searchMentionPositions	Array<SearchCursorPosition>	List of positions of all mentions
inputText	string	It's the text contained in the input field
setInputText	(text): string => void	Sets text inside textinput

This hook could be used to create you own custom component using some of this library logic. Let me know if you find it useful!

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT