prosemirror-suggest

Primitives for building your prosemirror suggestion and autocomplete functionality.

The problem

You want to create a plugin for your prosemirror editor that responds to an activation character to create suggesters or options or actions for the user. Doing this from scratch can be difficult.

This solution

prosemirror-suggest provides the suggestion primitives needed for building this functionality into your editor. You might be building user mentions, emoji search, an actions dropdown or anything that extracts a query from the editor after the activation character(s).

This implementation doesn't attempt to be magical. There's still a lot of work that goes into setting up your configuration. However, with this toolkit, you you will be building on a well-tested foundation with a structured API.

Installation

# yarn
yarn add prosemirror-suggest prosemirror-view prosemirror-state prosemirror-keymap

# pnpm
pnpm add prosemirror-suggest prosemirror-view prosemirror-state prosemirror-keymap

# npm
npm install prosemirror-suggest prosemirror-view prosemirror-state prosemirror-keymap

The installation requires the installation of the peer dependencies prosemirror-view, prosemirror-state and prosemirror-model to avoid version clashes.

Getting Started

This documentation will be updated soon.

prosemirror-suggest uses configuration objects called Suggester's to define the behaviour of the suggesters you create. By calling the exported suggest method with all required Suggester's the functionality is added to the editor in one plugin.

In the following example we're creating an emoji suggestion plugin that responds to the colon character with a query and presents a list of matching emojis based on the query typed so far.

import { schema } from 'prosemirror-schema-basic';
import { suggest, Suggester } from 'prosemirror-suggest';

const maxResults = 10;
let selectedIndex = 0;
let emojiList: string[] = [];
let showSuggestions = false;

const suggestEmojis: Suggester = {
  // By default decorations are used to highlight the currently matched
  // suggestion in the dom.
  // In this example we don't need decorations (in fact they cause problems when the
  // emoji string replaces the query text in the dom).
  noDecorations: true,
  char: ':', // The character to match against
  name: 'emoji-suggestion', // a unique name
  appendText: '', // Text to append to the created match

  // Keybindings are similar to prosemirror keymaps with a few extra niceties.
  // The key identifier can also include modifiers (e.g.) `Cmd-Space: () => false`
  // Return true to prevent any further keyboard handlers from running.
  keyBindings: {
    ArrowUp: () => {
      selectedIndex = rotateSelectionBackwards(selectedIndex, emojiList.length);
    },
    ArrowDown: () => {
      selectedIndex = rotateSelectionForwards(selectedIndex, emojiList.length);
    },
    Enter: ({ command }) => {
      if (showSuggestions) {
        command(emojiList[selectedIndex]);
      }
    },
    Esc: () => {
      showSuggestions = false;
    },
  },

  onChange: (params) => {
    const query = params.query.full;
    emojiList = sortEmojiMatches({ query, maxResults });
    selectedIndex = 0;
    showSuggestions = true;
  },

  onExit: () => {
    showSuggestions = false;
    emojiList = [];
    selectedIndex = 0;
  },

  // Create a  function that is passed into the change, exit and keybinding handlers.
  // This is useful when these handlers are called in a different part of the app.
  createCommand: ({ match, view }) => {
    return (emoji, skinVariation) => {
      if (!emoji) {
        throw new Error('An emoji is required when calling the emoji suggesters command');
      }

      const tr = view.state.tr;
      const { from, end: to } = match.range;
      tr.insertText(emoji, from, to);
      view.dispatch(tr);
    };
  },
};

// Create the plugin with the above configuration. It also supports multiple plugins being added.
const suggestionPlugin = suggest(suggestEmojis);

// Include the plugin in the created editor state.
const state = EditorState.create({ schema, plugins: [suggestionPlugin] });

You can see this example brought to life in the remirror codebase under the @remirror/extension-emoji and the @remirror/extension-mention packages.

The following examples are available for you to try out on the docs site

Search emoji on : key

The emojis are inserted as plain text. It’s up to you whether you insert the emoji as a node, mark or plaintext.

Editable mention on @ key

Each mention is a mark that wraps the mentioned text with a spec property of inclusive: false

Core API

suggest

This creates a suggestion plugin with all the suggesters provided.

Signature:

// eslint-disable-next-line @typescript-eslint/no-unused-expressions
(...suggesters: Suggester[]) => Plugin;

The priority of the suggesters is the order in which they are passed into this function.

const plugin = suggest(two, one, three);

In the above example two will be checked first, then one and then three.

Only one suggester can match at any given time. The order and specificity of the regex parameters help determines which suggester will be active.

Suggester

This Suggester interface defines all the options required to create a suggester within your editor.

Signature:

export interface Suggester<GCommand extends AnyFunction<void> = AnyFunction<void>>

Properties

Property	Type	Description
appendText	string	Text to append after the mention has been added.
char	string	The activation character(s) to match against.
ignoredClassName	string	Set a class for the ignored suggester decoration.
ignoredTag	string	Set a tag for the ignored suggester decoration.
invalidPrefixCharacters	RegExp | string	A regex expression used to invalidate the text directly before the match.
keyBindings	SuggestKeyBindingMap<GCommand>	An object that describes how certain key bindings should be handled.
matchOffset	number	Sets the characters that need to be present after the initial character match before a match is triggered.
name	string	A unique identifier for the suggester.
noDecorations	boolean	When true, decorations are not created when this mention is being edited..
startOfLine	boolean	Whether to only match from the start of the line
suggestClassName	string	Class name to use for the decoration (while the suggester is still being written)
suggestTag	string	Tag for the prosemirror decoration which wraps an active match.
supportedCharacters	RegExp | string	A regex containing all supported characters when within a suggester.
validPrefixCharacters	RegExp | string	A regex expression used to validate the text directly before the match.

Methods

Method	Description
createCommand(params)	Create the suggested actions which are made available to the onExit and ononChange handlers.
onChange(params)	Called whenever a suggester becomes active or changes in anyway.
onCharacterEntry(params)	Called for each character entry and can be used to disable certain characters.
onExit(params)	Called when a suggester is exited with the pre-exit match value.

The options are passed to the suggest method which uses them.

Package API

Enumerations

Enumeration	Description
ChangeReason	The potential reason for changes
ExitReason	The potential reasons for an exit of a mention.

Interfaces

Interface	Description
AddIgnoredParameter	The parameters needed for the SuggestIgnoreParameter.addIgnored() action method available to the suggest plugin handlers.
CompareMatchParameter	A parameter builder interface which compares the previous and next match.
CreateSuggestCommandParameter	The parameters passed into the createSuggest suggester property.
FromToEndParameter	A parameter builder interface describing a from/to/end range.
KeyboardEventParameter	A parameter builder interface describing the event which triggers the keyboard event handler.
MatchValue	The match value with the full and partial text.
OnKeyDownParameter	The parameters required by the .
ReasonMatchParameter	A parameter builder interface which adds the match property.
ReasonParameter	A parameter builder interface indicating the reason the handler was called.
RemoveIgnoredParameter	The parameters needed for the action method available to the suggest plugin handlers.
SuggestCallbackParameter
SuggestChangeHandlerParameter	The parameters passed to the Suggester.onChange() method.
SuggestCharacterEntryParameter	The parameters passed to the Suggester.onCharacterEntry() method.
SuggestCommandParameter	A parameter builder interface which adds the command property.
Suggester	This Suggester interface defines all the options required to create a suggestion within your editor.
SuggesterParameter
SuggestExitHandlerParameter	The parameters passed to the Suggester.onExit() method.
SuggestIgnoreParameter	A parameter builder interface describing the ignore methods available to the Suggester handlers.
SuggestKeyBindingParameter	The parameters required by the SuggestKeyBinding method.
SuggestMarkParameter	A special parameter needed when creating editable suggester using prosemirror Marks. The method should be called when removing a suggester that was identified by a prosemirror Mark.
SuggestReasonMap	A mapping of the handler matches with their reasons for occurring within the suggest state.
SuggestStateMatch	Describes the properties of a match which includes range and the text as well as information of the suggester that created the match.
SuggestStateMatchParameter	A parameter builder interface describing match found by the suggest plugin.
SuggestStateMatchReason

Variables

Variable	Description
createRegexFromSuggester	Create a regex expression to evaluate matches directly from the suggester properties.
DEFAULT_SUGGEST_ACTIONS
DEFAULT_SUGGESTER
escapeChar
getRegexPrefix	Find regex prefix when depending on whether the mention only supports the start of a line or not
getSuggestPluginState	Get the state of the suggest plugin.
isChange	Is this a change in the current suggestion (added or deleted characters)?
isChangeReason
isEntry	Are we entering a new suggestion?
isExit	Are we exiting a suggestion?
isExitReason	Check that the passed in value is an ExitReason
isInvalidSplitReason	Checks that the reason was caused by a split at a point where there is no query.
isJump	Is this a jump from one suggestion to another?
isJumpReason	Checks to see if this is a jump reason.
isMove	Has the cursor moved within the current suggestion (added or deleted characters)?
isRemovedReason	Checks that the reason was caused by a deletion.
isSplitReason	Checks that the reason passed is a split reason. This typically means that we should default to a partial update / creation of the mention.
isValidMatch	True when the match is currently active (i.e. it's query has a value)
regexToString	Convert a RegExp into a string
selectionOutsideMatch	True when the current selection is outside the match.
suggest	This creates a suggestion plugin with all the suggesters provided.

Type Aliases

Type Alias	Description
SuggestKeyBinding	A method for performing actions when a certain key / pattern is pressed.
SuggestKeyBindingMap	The keybindings shape for the Suggester.keyBindings property.
SuggestReplacementType	Determines whether to replace the full match or the partial match (up to the cursor position).