0.0.1 • Published 11 months ago
reactjs-text-mentions v0.0.1
reactjs-text-mentions
React library to handle @mentions, #channels, :smileys: and whatever with styles.
Getting started
Install the reactjs-text-mentions package via npm:
npm install reactjs-text-mentions --save
Or yarn:
yarn add reactjs-text-mentions
The package exports React components for rendering the mentions autocomplete and contenteditable :
import {
RichMentionsInput,
RichMentionsAutocomplete,
RichMentionsContext,
RichMentionsProvider,
} from 'reactjs-text-mentions';
RichMentionsProvider
- Feed it with your components and the mention configsRichMentionsInput
- The divcontenteditable used as TextFieldRichMentionsAutocomplete
- 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
0.0.1
11 months ago