Skip to main content

extension-mention

package @remirror/extension-mention

## The problem

You'd love a simpler way to create **editable** @ and # mentions with suggestions built into your remirror editor. Or perhaps you'd prefer non-editable mentions that create an inline prosemirror node. Or maybe you're keeping it simple and decide that you want mentions to output plain text into your markdown editor.

## The solution

@remirror/extension-mention exports three remirror extensions for managing **editable** Mark mentions, non-editable Node mentions and plain text mentions. Underneath the work is being done by prosemirror-suggest to reduce the boilerplate needed to setup.

## Installation

After completing the installation of the the remirror environment as shown in the [docs](https://remirror.io/docs/installation) run the following command.

yarn add @remirror/extension-mention # yarn
pnpm add @remirror/extension-mention # pnpm
npm install @remirror/extension-mention # npm

## Getting started

class MentionExtension​

The mention extension wraps mentions as a prosemirror mark. It allows for fluid social experiences to be built. The implementation was inspired by the way twitter and similar social sites allows mentions to be edited after they've been created.

Signature:

export declare class MentionExtension extends MarkExtension<MentionOptions>

Extends: MarkExtension<MentionOptions>

Remarks:

Mentions have the following features - An activation character or regex pattern which you define. - A min number of characters before mentions are suggested - Ability to exclude matching character. - Ability to wrap content in a decoration which excludes mentions from being suggested. - Decorations for in-progress mentions

(Some inherited members may not be shown because they are not represented in the documentation.)

property name​

Signature:

get name(): "mention";

method createEventHandlers​

Track click events passed through to the editor.

Signature:

createEventHandlers(): CreateEventHandlers;

Returns:

CreateEventHandlers

method createMarkSpec​

Signature:

createMarkSpec(extra: ApplySchemaAttributes, override: MarkSpecOverride): MarkExtensionSpec;

Parameters:

ParameterTypeDescription
extraApplySchemaAttributes
overrideMarkSpecOverride

Returns:

MarkExtensionSpec

method createMention​

Create a new mention

Signature:

createMention(config: NamedMentionExtensionAttributes & KeepSelectionProps): CommandFunction;

Parameters:

ParameterTypeDescription
configNamedMentionExtensionAttributes & KeepSelectionProps

Returns:

CommandFunction

method createPasteRules​

Manages the paste rules for the mention.

It creates regex tests for each of the configured matchers.

Signature:

createPasteRules(): MarkPasteRule[];

Returns:

MarkPasteRule[]

method createSuggesters​

Create the suggesters from the matchers that were passed into the editor.

Signature:

createSuggesters(): Suggester[];

Returns:

Suggester[]

method createTags​

Tag this as a behavior influencing mark.

Signature:

createTags(): ("behavior" | "excludeFromInputRules")[];

Returns:

("behavior" | "excludeFromInputRules")[]

method mentionExitHandler​

This is the command which can be called from the onChange handler to automatically handle exits for you. It decides whether a mention should be updated, removed or created and also handles invalid splits.

It does nothing for changes and only acts when an exit occurred.

Signature:

mentionExitHandler(handler: SuggestChangeHandlerProps, attrs?: MentionChangeHandlerCommandAttributes): CommandFunction;

Parameters:

ParameterTypeDescription
handlerSuggestChangeHandlerPropsthe parameter that was passed through to the onChange handler.
attrsMentionChangeHandlerCommandAttributes(Optional) the options which set the values that will be used (in case you want to override the defaults).

Returns:

CommandFunction

method onCreate​

Signature:

onCreate(): void;

Returns:

void

method removeMention​

Remove the mention(s) at the current selection or provided range.

Signature:

removeMention({ range }?: Partial<RangeProps>): CommandFunction;

Parameters:

ParameterTypeDescription
{ range }Partial<RangeProps>(Optional)

Returns:

CommandFunction

method updateMention​

Update an existing mention.

Signature:

updateMention(config: NamedMentionExtensionAttributes & KeepSelectionProps): CommandFunction;

Parameters:

ParameterTypeDescription
configNamedMentionExtensionAttributes & KeepSelectionProps

Returns:

CommandFunction

interface MentionExtensionMatcher​

The options for the matchers which can be created by this extension.

Signature:

export interface MentionExtensionMatcher extends Pick<Suggester, 'char' | 'name' | 'startOfLine' | 'supportedCharacters' | 'validPrefixCharacters' | 'invalidPrefixCharacters' | 'matchOffset' | 'suggestClassName'>

Extends: Pick<Suggester, 'char' | 'name' | 'startOfLine' | 'supportedCharacters' | 'validPrefixCharacters' | 'invalidPrefixCharacters' | 'matchOffset' | 'suggestClassName'>

(Some inherited members may not be shown because they are not represented in the documentation.)

property appendText​

Text to append after the suggestion has been added.

Signature:

appendText?: string;

property mentionClassName​

Provide customs class names for the completed mention

Signature:

mentionClassName?: string;

interface MentionOptions​

The static settings passed into a mention

Signature:

export interface MentionOptions extends Pick<Suggester, 'invalidNodes' | 'validNodes' | 'invalidMarks' | 'validMarks' | 'isValidPosition' | 'disableDecorations'>

Extends: Pick<Suggester, 'invalidNodes' | 'validNodes' | 'invalidMarks' | 'validMarks' | 'isValidPosition' | 'disableDecorations'>

(Some inherited members may not be shown because they are not represented in the documentation.)

property appendText​

Text to append after the mention has been added.

**NOTE**: If you're using whitespace characters but it doesn't seem to work for you make sure you're using the css provided in @remirror/styles.

The white-space: pre-wrap; is what allows editors to add space characters at the end of a section.

Signature:

appendText?: string;

property isMentionValid​

A predicate check for whether the mention is valid. It proves the mention mark and it's attributes as well as the text it contains.

This is used for checking that a recent update to the document hasn't made a mention invalid.

For example a mention for @valid => valid would be considered invalidating. Return false to remove the mention.

Signature:

isMentionValid?: (attrs: NamedMentionExtensionAttributes, text: string) => boolean;

property matchers​

Provide the custom matchers that will be used to match mention text in the editor.

Signature:

matchers: Static<MentionExtensionMatcher[]>;

property mentionTag​

Provide a custom tag for the mention

Signature:

mentionTag?: Static<string>;

property onChange​

Called whenever a suggestion becomes active or changes in any way.

Signature:

onChange?: Handler<MentionChangeHandler>;

Remarks:

It receives a parameters object with the reason for the change for more granular control.

The second parameter is a function that can be called to handle exits automatically. This is useful if you're mention can be any possible value, e.g. a #hashtag. Call it with the optional attributes to automatically create a mention.

property onClick​

Listen for click events to the mention extension.

Signature:

onClick?: Handler<(event: MouseEvent, markRange: GetMarkRange) => boolean | undefined | void>;

property suggestTag​

Tag for the prosemirror decoration which wraps an active match.

Signature:

suggestTag?: string;

interface OptionalMentionExtensionProps​

Signature:

export interface OptionalMentionExtensionProps

property appendText​

The text to append to the replacement.

Signature:

appendText?: string;

property range​

The range of the requested selection.

Signature:

range?: RangeWithCursor;

property replacementType​

Whether to replace the whole match (full) or just the part up until the cursor (partial).

Signature:

replacementType?: keyof MatchValue;

type MentionChangeHandler​

A handler that will be called whenever the the active matchers are updated or exited. The second argument which is the exit command is a function which is only available when the matching suggester has been exited.

Signature:

export type MentionChangeHandler = (handlerState: MentionChangeHandlerProps, command: (attrs?: MentionChangeHandlerCommandAttributes) => void) => void;

References: MentionChangeHandlerCommandAttributes

type MentionChangeHandlerCommand​

Signature:

export type MentionChangeHandlerCommand = (attrs?: MentionChangeHandlerCommandAttributes) => void;

References: MentionChangeHandlerCommandAttributes

type MentionChangeHandlerCommandAttributes​

The dynamic properties used to change the behavior of the mentions created.

Signature:

export type MentionChangeHandlerCommandAttributes = ProsemirrorAttributes<Partial<Pick<MentionExtensionAttributes, 'appendText' | 'replacementType'>> & {
    id?: string;
    label?: string;
}>;

References: ProsemirrorAttributes, MentionExtensionAttributes

type MentionExtensionAttributes​

The attrs that will be added to the node. ID and label are plucked and used while attributes like href and role can be assigned as desired.

Signature:

export type MentionExtensionAttributes = ProsemirrorAttributes<OptionalMentionExtensionProps & {
    id: string;
    label: string;
}>;

References: ProsemirrorAttributes, OptionalMentionExtensionProps

type NamedMentionExtensionAttributes​

Signature:

export type NamedMentionExtensionAttributes = ProsemirrorAttributes<OptionalMentionExtensionProps & {
    id: string;
    label: string;
} & {
    name: string;
}>;

References: ProsemirrorAttributes, OptionalMentionExtensionProps