Skip to content

@mentions people, or #channels, or :smileys: on contenteditable element with styles

License

Notifications You must be signed in to change notification settings

koala-interactive/react-rich-mentions

Repository files navigation

react-rich-mentions

GitHub package.json dependency version (prod) Cypress.io lint e2e

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 div[contenteditable] 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

Prop name Type Default value Description
defaultValue string '' The default value of the input (cannot be updated)

RichMentionsAutocomplete props

Prop name Type Default value Description
fixed boolean (optional) false Is the autocomplete on a fixed position element ?

RichMentionsProvider props

Prop name Type Default value Description
configs TMentionConfig[] undefined List of configs to fetch mentions
getContext function (optional) undefined Get rich mention context (can be used with a useRef)
getInitialHTML function (optional) undefined Can be used to overwrite the function used to preprocess value data

RichMentionsPublicContext props

The context returned by getContext props.

Prop name Type Example Description
getTransformedValue function const text = ctx.getTransformedValue() Get the input value with fragment transformed to valid code
setValue function ctx.setValue('Hello <@world|U15151>') Change the input value, will transform the code with valid fragment. It's possible to insert HTML so make sure to sanitize your user's input. Note that for a valid html to be set, you will have to add the following html attribute so it's not remove from the engine data-rich-mentions=":smile:" where ":smile:" is the final extracted reference
insertFragment function ctx.insertFragment('<@world|U45454>') Add a fragment at the current cursor position

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.