Git Product home page Git Product logo

react-rich-mentions's Introduction

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.

react-rich-mentions's People

Contributors

dokoliday avatar muzishell avatar tai-koala avatar vthibault avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.