prosemirror-autocomplete

!CI

A plugin for ProseMirror that adds triggers for #hashtags, @mentions, /menus, and other more complex autocompletions. The prosemirror-autocomplete library can be used to create suggestions similar to Notion, Google Docs or Confluence; it is created and used by Curvenote. The library does not provide a user interface beyond the demo code.


Install

``bash
npm install prosemirror-autocomplete
`

Or see the live demo here!

Overview

prosemirror-autocomplete allows you to have fine-grained control over an autocomplete suggestion, similar to an IDE but simple enough for @ or # mentions.

`ts
import autocomplete, { Options } from 'prosemirror-autocomplete';

// Create autocomplete with triggers and specified handers:
const options: Options = {
triggers: [
{ name: 'hashtag', trigger: '#' },
{ name: 'mention', trigger: '@' },
],
onOpen: ({ view, range, trigger, type }) => handleOpen(),
onArrow: ({ view, kind }) => handleArrow(kind),
onFilter: ({ view, filter }) => handleFilter(),
onEnter: ({ view }) => handleSelect(),
onClose: ({ view }) => handleClose(),
};

// Alternatively, use a single reducer to handle all actions:
const options: Options = {
triggers: [
{ name: 'hashtag', trigger: '#' },
{ name: 'mention', trigger: '@' },
],
reducer: (action) => dispatch(action),
};

// Then add these plugins to the EditorView as normal in ProseMirror
const view = new EditorView(editor, {
state: EditorState.create({
doc: DOMParser.fromSchema(schema).parse(content),
plugins: [...autocomplete(options), ...otherPlugins],
}),
});
`

The function autocomplete takes handlers or a single reducer and a list of triggers, it returns a two plugins:

1. a decoration plugin that wraps the trigger and filter text (e.g. [@][mention]); and
2. an InputRule plugin that has a series of triggers that are defined in the options.

All handlers take an AutocompleteAction as the first and only argument (same as the reducer).

- onOpen({ view, range, trigger, filter, type }) — when the autocomplete should be opened
- The type is the Trigger that cause this action
- onEnter({ view, range, filter }) — called on Enter or Tab
- onArrow({ view, kind })
- kind is one or ArrowUp, ArrowDown, ArrowLeft, ArrowRight
- left/right are only called if allArrowKeys = true for the trigger
- onFilter({ view, filter }) — called when the user types, use this to filter the suggestions shown
- onClose({ view }) — called on escape, click away, or paste

To use a reducer instead of distinct handlers, use the option reducer: (action: AutocompleteAction) => boolean, which will be used in place of the above handler functions.

Defining a Trigger

By default, each Trigger has a name, and a trigger, which is a string or RegExp. For example, a simple trigger can just use a single string:

`ts
import type { Trigger } from 'prosemirror-autocomplete';

const mentionTrigger: Trigger = { name: 'mention', trigger: '@' };
`

This trigger gets wrapped in a regular expresion:

`ts
const equivalentTrigger = /(?:^|\s|\n|[^\d\w])(@)$/;
`

This does what you want most of the time, ensuring that you don't trigger when writing an email, or if you are writing something else. This is a bit more strict than you might want for a social plugin, which picks up hashtags or mentions anywhere you write them.

If you want this to come up all the time, try:

`ts
const peskyMentionTrigger: Trigger = { name: 'mention', trigger: /(@)$/ };
`

Provide the trigger in the matched group and anything before in a non-capture group ((?:)), this will help you split the action into a action.search and an action.trigger.

$3

- name: string: the trigger is passed in the action, you can use this to descriminate handler calls
- trigger: string | RegExp: used to trigger an autocomplete suggestion - described above
- cancelOnFirstSpace?: boolean, cancels the auto complete on first space, default is true
- allArrowKeys?: boolean: Use left/right arrow keys, default is false
- decorationAttrs?: DecorationAttrs, passed to the element directly through prosemirror

Defining a Reducer

The library does not provide a user interface beyond the demo code, you will have to do that when you get an action from the autocomplete plugin. You can _either_ use the handlers onOpen, onArrow, onFilter, onEnter, and onClose _or_ you can define a single reducer that will take over these responsibilities. Note: you cannot use handlers and a reducer. You can also access the original keyboard event on the action, as action.event. If the action was not created by a keyboard event, that property will not be available.

`ts
import { AutocompleteAction, KEEP_OPEN } from 'prosemirror-autocomplete';

export function reducer(action: AutocompleteAction): boolean | KEEP_OPEN {
switch (action.kind) {
case ActionKind.open:
handleSearch(action.search);
placeSuggestion(true);
return true;
case ActionKind.up:
selectSuggestion(-1);
return true;
case ActionKind.down:
selectSuggestion(+1);
return true;
case ActionKind.filter:
filterSuggestions(action.filter);
return true;
case ActionKind.enter:
// This is on Enter or Tab
const { from, to } = action.range;
const tr = action.view.state.tr
.deleteRange(from, to) // This is the full selection
.insertText('You can define this!'); // This can be a node view, or something else!
action.view.dispatch(tr);
return true;
// To keep the suggestion open after selecting:
return KEEP_OPEN;
case ActionKind.close:
// Hit Escape or Click outside of the suggestion
closeSuggestion();
return true;
default:
return false;
}
}
`

An AutocompleteAction is passed to both the reducer and each handler has the following structure:

`ts
export type AutocompleteAction = {
kind: ActionKind; // open, ArrowUp, ArrowDown, filter, enter, close
view: EditorView; // the view that the plugin came from
trigger: string; // This is the string that triggered the suggestion
filter?: string; // This is the search string
range: FromTo; // { from: number; to: number }, use to delete the selection
type: Trigger | null; // This is the trigger object passed in
};
`

Positioning & Styling

You can use something like popper.js to ensure that the autocomplete suggestions stay in the right place on scroll or simply an abolutely positioned