@rickybento/react-rich-mentions v0.1.10

react-rich-mentions

React library to handle @mentions, #channels, :smileys: and whatever with styles.

Getting started

Install the react-rich-mentions package via npm:

npm install react-rich-mentions --save

Or yarn:

yarn add react-rich-mentions

The package exports React components for rendering the mentions autocomplete and contenteditable :

import {
  RichMentionsInput,
  RichMentionsAutocomplete,
  RichMentionsContext,
  RichMentionsProvider,
} from 'react-rich-mentions';

• RichMentionsProvider - Feed it with your components and the mention configs
• RichMentionsInput - The divcontenteditable used as TextField
• RichMentionsAutocomplete - The default Autocomplete component given with the library (can be overwritten)
• RichMentionsContext - Use it to create your own Autocomplete or custom controller.

Example:

const configs = [
  {
    // The fragment to transform to readable element.
    // For example, slack is using `<[name]|[id]>` -> `<vince|U82737823>`
    match: /<(@\w+)\|([^>]+)>/g,

    // Use it in combinaison with .match to choose what to display to your user instead of the fragment
    // Given the regex `/<(@\w+)\|([^>]+)>/g` and the fragment `<vince|U82737823>`
    // - $& -> <vince|U82737823>
    // - $1 -> vince
    // - $2 -> U82737823
    matchDisplay: '$1',

    // The query that will start the autocomplete
    // In this case it will match:
    // - @
    // - @test
    // _ @test_
    // Can be changed to catch spaces or some special characters.
    query: /@([a-zA-Z0-9_-]+)?/,

    // The function that will search for autocomplete result.
    // The argument is the searchable text (for example '@test').
    // It can return a promise. The result have to contains for each item:
    // - a prop "ref" -> let say `<@vince|U23872783>`
    // - a prop "name" -> the display name
    async onMention(text) {
      const query = text.substr(1); // remove the '@'
      const results = await callYourAPI(query);

      return results.map(user => ({
        ref: `<@${user.nickname}|${user.id}>`,
        name: user.nickname,
      }));
    },

    // Called to customize visual elements inside input.
    // Can be used to add classes, aria, ...
    // `final` is a boolean to know if the fragment is resolved still
    // waiting for user to select an entry in autocomplete
    customizeFragment(span: HTMLSpanElement, final: boolean) {
      span.className = final ? 'final' : 'pending';
    },
  },
];

const MyComponent = () => {
  const ref = useRef();
  const onClear = () => ref.current.setValue('');
  const onSubmit = () => {
    console.log(ref.current.getTransformedValue());
  };

  return (
    <RichMentionsProvider configs={configs} getContext={ref}>
      <RichMentionsInput defaultValue="The default Text" />
      <RichMentionsAutocomplete fixed={false} />
      <button type="button" onClick={onSubmit}>
        Send
      </button>
      <button type="reset" onClick={onClear}>
        Clear
      </button>
    </RichMentionsProvider>
  );
};

RichMentionsInput props

RichMentionsAutocomplete props

RichMentionsProvider props

RichMentionsPublicContext props

The context returned by getContext props.

Building Locally

After cloning the repository, install all dependencies :

yarn

or

npm install

Testing

To test this project, we use cypress : https://docs.cypress.io/guides/overview/why-cypress.html

cd ./examples
yarn (OR npm install)
cd ..
yarn cypress:headless

If you develop a new feature, be sure to add tests in the cypress folder, following documentation from the above website.