A plugin for ProseMirror that helps you add suggestions to your editor.
"Suggestions" is a loose concept; while we originally designed this plugin around @mentions
or #hash-tags
, we hope
that it can be adapted to other use cases.
This plugin will not render any UI for you. The goal is to handle triggers, giving you tools to render your own UI elements however you choose.
yarn add @quartzy/prosemirror-suggestions
An example project can be found in the example
folder in this repository.
To use this plugin, first import the helpers:
import {
addMentionNodes,
suggestionsPlugin,
triggerCharacter
} from "@quartzy/prosemirror-suggestions";
// Or, for commonjs:
// const { addMentionNodes, suggestionsPlugin, triggerCharacter } = require('@quartzy/prosemirror-suggestions');
Next extend the nodes
of your schema with addMentionNodes
:
import { Schema } from "prosemirror-model";
import { schema as basicSchema } from "prosemirror-schema-basic";
const schema = new Schema({
nodes: addMentionNodes(basicSchema.spec.nodes),
marks: basicSchema.spec.marks
});
Finally add suggestionsPlugin(...)
to your list of plugins:
const plugins = [
suggestionsPlugin({
debug: true,
matcher: triggerCharacter("@", { allowSpaces: true }),
onEnter(args) {
console.log("start", args);
return false;
},
onChange(args) {
console.log("change", args);
return false;
},
onExit(args) {
console.log("stop", args);
return false;
},
onKeyDown({ view, event }) {
// console.log(event.key);
return false;
}
})
/* OTHER PLUGINS HERE */
];
suggestionsPlugin
accepts the following options:
matcher
— determines when to trigger suggestions; defaults totriggerCharacter('#')
suggestionClass
— adds a class to the active suggestion; defaults to'ProseMirror-suggestion'
debug
— adds a blue background/border to the active suggestion; defaults tofalse
onEnter({ view, range, text})
— when entering suggestion mode (return value ignored)onChange({view, range, text})
— when the current suggestion text changes (return value ignored)onExit({view, range, text})
— when leaving suggestion mode (return value ignored)onKeyDown({view, event})
— equivalent to the ProseMirrorhandleKeyDown
callback, except only called when suggestion is active (returntrue
to prevent default, otherwise returnfalse
)
# Run tests
yarn test
# Build distributable
yarn build
# Build and watch for changes
yarn watch
The Apache License, v2.0. Please see License File for more information.