• Stars
    star
    2,445
  • Rank 18,802 (Top 0.4 %)
  • Language
    JavaScript
  • License
    Other
  • Created almost 10 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

@mention people in a textarea

React Mentions

REUSE status

A React component that let's you mention people in a textarea like you are used to on Facebook or Twitter.

Used in production at Signavio, State, Snips, Swat.io, GotDone, Volinspire, Marvin, Timely, GuideFitter, Evite, Publer, Kontentino, Wix.com, Highlight and you?

Getting started

Install the react-mentions package via npm:

npm install react-mentions --save

Or yarn:

yarn add react-mentions

The package exports two React components for rendering the mentions textarea:

import { MentionsInput, Mention } from 'react-mentions'

MentionsInput is the main component rendering the textarea control. It takes one or multiple Mention components as its children. Each Mention component represents a data source for a specific class of mentionable objects, such as users, template variables, issues, etc.

Example:

<MentionsInput value={this.state.value} onChange={this.handleChange}>
  <Mention
    trigger="@"
    data={this.props.users}
    renderSuggestion={this.renderUserSuggestion}
  />
  <Mention
    trigger="#"
    data={this.requestTag}
    renderSuggestion={this.renderTagSuggestion}
  />
</MentionsInput>

You can find more examples here: demo/src/examples

Configuration

The MentionsInput supports the following props for configuring the widget:

Prop name Type Default value Description
value string '' The value containing markup for mentions
onChange function (event, newValue, newPlainTextValue, mentions) empty function A callback that is invoked when the user changes the value in the mentions input
onKeyDown function (event) empty function A callback that is invoked when the user presses a key in the mentions input
singleLine boolean false Renders a single line text input instead of a textarea, if set to true
onBlur function (event, clickedSuggestion) empty function Passes true as second argument if the blur was caused by a mousedown on a suggestion
allowSpaceInQuery boolean false Keep suggestions open even if the user separates keywords with spaces.
suggestionsPortalHost DOM Element undefined Render suggestions into the DOM in the supplied host element.
inputRef React ref undefined Accepts a React ref to forward to the underlying input element
allowSuggestionsAboveCursor boolean false Renders the SuggestionList above the cursor if there is not enough space below
forceSuggestionsAboveCursor boolean false Forces the SuggestionList to be rendered above the cursor
a11ySuggestionsListLabel string '' This label would be exposed to screen readers when suggestion popup appears
customSuggestionsContainer function(children) empty function Allows customizing the container of the suggestions

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

Prop name Type Default value Description
trigger regexp or string '@' Defines the char sequence upon which to trigger querying the data source
data array or function (search, callback) null An array of the mentionable data entries (objects with id & display keys, or a filtering function that returns an array based on a query parameter
renderSuggestion function (entry, search, highlightedDisplay, index, focused) null Allows customizing how mention suggestions are rendered (optional)
markup string '@[__display__](__id__)' A template string for the markup to use for mentions
displayTransform function (id, display) returns display Accepts a function for customizing the string that is displayed for a mention
regex RegExp automatically derived from markup pattern Allows providing a custom regular expression for parsing your markup and extracting the placeholder interpolations (optional)
onAdd function (id, display, startPos, endPos) empty function Callback invoked when a suggestion has been added (optional)
appendSpaceOnAdd boolean false Append a space when a suggestion has been added (optional)

If a function is passed as the data prop, that function will be called with the current search query as first, and a callback function as second argument. The callback can be used to provide results asynchronously, e.g., after fetch requests. (It can even be called multiple times to update the list of suggestions.)

Styling

react-mentions supports css, css modules, and inline styles. It is shipped with only some essential inline style definitions and without any css. Some example inline styles demonstrating how to customize the appearance of the MentionsInput can be found at demo/src/examples/defaultStyle.js.

If you want to use css, simply assign a className prop to MentionsInput. All DOM nodes rendered by the component will then receive class name attributes that are derived from the base class name you provided.

If you want to avoid global class names and use css modules instead, you can provide the automatically generated class names as classNames to the MentionsInput. See demo/src/examples/CssModules.js for an example of using react-mentions with css modules.

You can also assign className and style props to the Mention elements to define how to highlight the mentioned words.

Testing

Due to react-mentions' internal cursor tracking it is not good enough to simulate the editing of the textarea value using ReactTestUtils.Simulate.change. We recommend using @testing-library/user-event for a realistic simulation of events as they would happen in the browser as the user interacts the textarea.


If you want to contribute, first of all: thank you ❀️. Please check CONTRIBUTING.md and/or create an issue.

More Repositories

1

react-stick

React component to stick a portaled node to an anchor node
TypeScript
64
star
2

signa

Chatops toolkit for Slack. Support to Kubernetes and much more!
Go
28
star
3

sap-sam

Example source code for SAP Signavio Academic Models (SAP-SAM)
Jupyter Notebook
28
star
4

BPMN-Sol

Compiler to convert BPMN 2.0 xml to solidity smart contract
TypeScript
16
star
5

i18n

Minimalist gettext style i18n for JavaScript
JavaScript
15
star
6

aws-mfa-login

small CLI tool to do aws with mfa and update credentials in local aws config
Go
15
star
7

pimba

Pimba is a minimalist command-line tool written in Go to publish and serve static files.
Go
12
star
8

tech-blog

Signavio Tech Blog
SCSS
10
star
9

bpmn2constraints

Translates BPMN models to declarative constraints in different languages (DECLARE, SIGNAL, LTLf)
Python
9
star
10

eslint-config-signavio

JavaScript
3
star
11

connector-examples

This repository includes examples for different types of connectors that can be used with Signavio Workflow Accelerator
Java
3
star
12

binge

JavaScript
2
star
13

dmn-and-drools-execution-examples

Java
2
star
14

on-premise

Shell
2
star
15

workflow-connector

Signavio Workflow Accelerator Connector
Go
2
star
16

tools-orb

Orb that contains install script for various tools
Shell
1
star
17

backbone-partialput

Only send changed attributes of Backbone models to the server.
JavaScript
1
star
18

plantuml-converter

Go
1
star
19

circleci-aws-ecr-eks-orb

CircleCi Orb to build and push to AWS ECR and deploy to EKS via kubectl rollout restart
1
star
20

antlr4rust

Rust
1
star
21

workflow-on-premise

1
star
22

backbone-rel

**UNMAINTAINED** Relationships between Backbone models in the flavor of MongoDB's document references and embeddings
JavaScript
1
star
23

asdf-aws-mfa-login

Shell
1
star
24

Test-Driven-Process-Modeling

Test-driven Process Modelingfor Smart Contract Specification
TypeScript
1
star
25

lassoer

A collection of utilities to help you wrangle misbehaving text files into a SQL database
R
1
star