prosemirror-suggest

prosemirror-suggest

The problem

You want to create a suggestion plugin for your prosemirror editor but are unsure how to get started. The suggestions could be for mentions, emojis, responding to a keypress with a dropdown of potential actions or anything that needs to extract a query from the current editor when a matching character is entered.

This solution

prosemirror-suggest provides the suggestion primitives you will need for within your editor. It doesn't try to be magical and even with this library setting up suggestions can be difficult. However, with this toolkit, you will be able to build pretty much any suggestion plugin you can think of.

Installation

yarn add prosemirror-suggest prosemirror-view

Getting Started

The configuration of prosemirror-suggests is based on a Suggester interface which defines the suggestion behaviour. The suggest method receives the configured suggestersand creates a suggestion plugin which can be used within your prosemirror editor.

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.

import { Suggester, suggest } 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).
   */
  ignoreDecorations: 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 suggestions 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 supports multiple plugins being added.
const suggestionPlugin = suggest(suggestEmojis, suggestMentions);

// Later on in the codebase
const state = EditorState.create({
  schema,
  plugins: [suggestionPlugin],
});

API

suggest variable

This creates a suggestion plugin with all the suggestions provided.

Signature:

suggest: <GSchema extends import("prosemirror-model").Schema<string, string> = any>(...suggesters: Suggester<import("@remirror/core-types").AnyFunction<void>>[]) => Plugin<SuggestState<any>, GSchema>

The priority of the suggestions 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 suggestion can match at any given time. The order and specificity of the regex parameters help determines which suggestion will be active.

Suggester interface

This Suggester interface provides the options object which is used within the suggest plugin creator.

Properties

Property	Type	Description
appendText	string	Text to append after the mention has been added.
char	string	The character to match against.
decorationsTag	keyof HTMLElementTagNameMap	Tag which wraps an active match.
ignoreDecorations	boolean	When true, decorations are not created when this mention is being edited..
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.For example with char = @ the following is true.- matchOffset: 0 matches '@' immediately - matchOffset: 1 matches '@a' but not '@' - matchOffset: 2 matches '@ab' but not '@a' or '@' - matchOffset: 3 matches '@abc' but not '@ab' or '@a' or '@' - And so on...
name	string	A unique identifier for the matching character.
startOfLine	boolean	Whether to only match from the start of the line
suggestionClassName	string	Class name to use for the decoration (while the plugin is still being written)
supportedCharacters	RegExp | string	A regex containing all supported characters when within a suggestion.
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.
getStage(params)	Check the current match and editor state to determine whether this match is being newly created or edited.
onChange(params)	Called whenever a suggestion 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 suggestion is exited with the pre-exit match value.