Skip to main content

extension-mention-atom

package @remirror/extension-mention-atom

## 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-atom 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-atom # yarn
pnpm add @remirror/extension-mention-atom # pnpm
npm install @remirror/extension-mention-atom # npm

## Getting started

class MentionAtomExtension​

This is the atom version of the MentionExtension @remirror/extension-mention.

It provides mentions as atom nodes which don't support editing once being inserted into the document.

Signature:

export declare class MentionAtomExtension extends NodeExtension<MentionAtomOptions>

Extends: NodeExtension<MentionAtomOptions>

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

property name​

Signature:

get name(): "mentionAtom";

method createEventHandlers​

Track click events passed through to the editor.

Signature:

createEventHandlers(): CreateEventHandlers;

Returns:

CreateEventHandlers

method createMentionAtom​

Creates a mention atom at the the provided range.

A variant of this method is provided to the onChange handler for this extension.

Signature:

createMentionAtom(details: CreateMentionAtom, attrs: MentionAtomNodeAttributes): CommandFunction;

Parameters:

ParameterTypeDescription
detailsCreateMentionAtomthe range and name of the mention to be created.
attrsMentionAtomNodeAttributesthe attributes that should be passed through. Required values are id and label.

Returns:

CommandFunction

method createNodeSpec​

Signature:

createNodeSpec(extra: ApplySchemaAttributes, override: NodeSpecOverride): NodeExtensionSpec;

Parameters:

ParameterTypeDescription
extraApplySchemaAttributes
overrideNodeSpecOverride

Returns:

NodeExtensionSpec

method createSuggesters​

Signature:

createSuggesters(): Suggester[];

Returns:

Suggester[]

method createTags​

Signature:

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

Returns:

("inline" | "behavior")[]

interface CreateMentionAtom​

Signature:

export interface CreateMentionAtom

property name​

The name of the matcher used to create this mention.

Signature:

name: string;

property range​

The range of the current selection

Signature:

range: RangeWithCursor;

interface MentionAtomExtensionMatcher​

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

Signature:

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

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

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

property matchOffset​

See [[``Suggester.matchOffset`]] for more details.

Signature:

matchOffset?: number;

property mentionClassName​

Provide customs class names for the completed mention.

Signature:

mentionClassName?: string;

property mentionTag​

An override for the default mention tag. This allows different mentions to use different tags.

Signature:

mentionTag?: string;

interface MentionAtomOptions​

Options available to the [[MentionAtomExtension]].

Signature:

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

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

(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 it seems that your editor is swallowing up empty whitespace, make sure you've imported the core css from the @remirror/styles library.

Signature:

appendText?: string;

property disableDecorations​

When true, decorations are not created when this mention is being edited.

Signature:

disableDecorations?: boolean;

property draggable​

Whether mentions should be draggable.

Signature:

draggable?: Static<boolean>;

property matchers​

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

TODO - add customized tags here.

Signature:

matchers: Static<MentionAtomExtensionMatcher[]>;

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<MentionAtomChangeHandler>;

Remarks:

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

property onClick​

Listen for click events to the mention atom extension.

Signature:

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

property selectable​

When true the atom node which wraps the mention will be selectable.

Signature:

selectable?: Static<boolean>;

property suggestTag​

Tag for the prosemirror decoration which wraps an active match.

Signature:

suggestTag?: string;

interface OptionalMentionAtomExtensionProps​

Signature:

export interface OptionalMentionAtomExtensionProps

property appendText​

The text to append to the replacement.

Signature:

appendText?: string;

property replacementType​

The type of replacement to use. By default, the command will replace the entire match.

To replace the match up only to where the cursor is placed set this to partial.

Signature:

replacementType?: keyof MatchValue;

type MentionAtomChangeHandler​

This change handler is called whenever there is an update in the matching suggester. The second parameter command is available to automatically create the mention with the required attributes.

Signature:

export type MentionAtomChangeHandler = (handlerState: SuggestChangeHandlerProps, command: (attrs: MentionAtomNodeAttributes) => void) => void;

References: SuggestChangeHandlerProps, MentionAtomNodeAttributes

type MentionAtomNodeAttributes​

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 MentionAtomNodeAttributes = ProsemirrorAttributes<OptionalMentionAtomExtensionProps & {
    id: string;
    label: string;
}>;

References: ProsemirrorAttributes, OptionalMentionAtomExtensionProps

type NamedMentionAtomNodeAttributes​

Signature:

export type NamedMentionAtomNodeAttributes = MentionAtomNodeAttributes & {
    name: string;
};

References: MentionAtomNodeAttributes