https://github.com/joelewis/prosemirror-mentions
ProseMirror plugin to enable @mentions and #hashtags
https://github.com/joelewis/prosemirror-mentions
javascript-library prosemirror
Last synced: 4 months ago
JSON representation
ProseMirror plugin to enable @mentions and #hashtags
- Host: GitHub
- URL: https://github.com/joelewis/prosemirror-mentions
- Owner: joelewis
- License: mit
- Created: 2019-01-16T21:48:14.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-04-15T09:03:21.000Z (about 2 years ago)
- Last Synced: 2025-11-27T09:33:28.940Z (6 months ago)
- Topics: javascript-library, prosemirror
- Language: JavaScript
- Size: 1.61 MB
- Stars: 123
- Watchers: 5
- Forks: 34
- Open Issues: 32
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ProseMirror Mentions
A [ProseMirror](https://prosemirror.net/) plugin that enables @mentions and #hashtags in a prosemirror view.
Demo: [https://star-drug.glitch.me/](https://star-drug.glitch.me/)
Alternative: [https://github.com/quartzy/prosemirror-suggestions](https://github.com/quartzy/prosemirror-suggestions)
## What's different then?
[prosemirror-suggestions](https://github.com/quartzy/prosemirror-suggestions) is a lighter alternative that comes with the bare minimum. It is upto you to implement the dropdown & related logic.
[prosemirror-mentions](https://github.com/joelewis/prosemirror-mentions) is a fully packed plugin. It comes with all batteries included: default dropdown UI, behavior handling, support for async fetching of suggestions, etc. [Configure options to suit your needs](#complete-list-of-options).
## Installation
```bash
npm install prosemirror-mentions
```
## Usage
```js
import {addMentionNodes, addTagNodes, getMentionsPlugin} from 'prosemirror-mentions'
...
...
var schema = new Schema({
nodes: addTagNodes(addMentionNodes(schema.spec.nodes)),
marks: schema.spec.marks
});
...
...
/**
* IMPORTANT: outer div's "suggestion-item-list" class is mandatory. The plugin uses this class for querying.
* IMPORTANT: inner div's "suggestion-item" class is mandatory too for the same reasons
*/
var getMentionSuggestionsHTML = items => '
'+
items.map(i => ''+i.name+'').join('')+
'';
/**
* IMPORTANT: outer div's "suggestion-item-list" class is mandatory. The plugin uses this class for querying.
* IMPORTANT: inner div's "suggestion-item" class is mandatory too for the same reasons
*/
var getTagSuggestionsHTML = items => '
'+
items.map(i => ''+i.tag+'').join('')+
'';
var plugins = [/* A list of other plugins */]
var mentionPlugin = getMentionsPlugin({
getSuggestions: (type, text, done) => {
setTimeout(() => {
if (type === 'mention') {
// pass dummy mention suggestions
done([{name: 'John Doe', id: '101', email: 'joe@gmail.com'}, {name: 'Joe Lewis', id: '102', email: 'lewis@gmail.com'}])
} else {
// pass dummy tag suggestions
done([{tag: 'WikiLeaks'}, {tag: 'NetNeutrality'}])
}
}, 0);
},
getSuggestionsHTML: (items, type) => {
if (type === 'mention') {
return getMentionSuggestionsHTML(items)
} else if (type === 'tag') {
return getTagSuggestionsHTML(items)
}
}
});
plugins.unshift(mentionPlugin); // push it before keymap plugin to override keydown handlers
...
...
window.view = new EditorView(document.querySelector("#my-editor-div"), {
state: EditorState.create({
schema: schema,
plugins: plugins
})
});
```
Refer [example application](https://github.com/joelewis/prosemirror-mentions/tree/master/example) for clarifications.
## Complete List of Options
```js
// default options
var defaultOpts = {
// char for triggering @mention
mentionTrigger: "@",
// char for triggering #tag
hashtagTrigger: "#",
// if true: allows you to type @FirstName LastName with a space in between.
allowSpace: true,
/**
* callback to fetch suggestions and return a list of suggestions
* @param {String} type - 'mention' or 'tag'
* @param {String} text - query text. For e.g @Joh -> text = 'Joh'
* @param {Function} done - callback to execute after fetching suggestions (ideally from ajax requests)
*/
getSuggestions: (type, text, done) => {
done([]);
},
/**
* callback to construct and return a HTML string for a set of suggestions
* @param {Array} items - a list of suggestions returned from getSuggestions()
* @param {String} type - 'mention' or 'tag'
*/
getSuggestionsHTML: (items, type) =>
'
' +
items
.map(i =>
'' + type === "mention"
? i.name
: i.tag + ""
)
.join("") +
"",
// css class to add when a .suggestion-item element is active / selected.
activeClass: "suggestion-item-active",
// css class to add to "@Mentioned Text" in editor. Can be used to style, the current active @mention content.
suggestionTextClass: "prosemirror-suggestion",
// Max number of suggestions to show in dropdown UI.
// The response from getSuggestions() will be truncated based on this value.
maxNoOfSuggestions: 10,
// debounce timeout for getSuggestions() call when user types continuously
delay: 500
};
```
## Development
```bash
npm run build
npm run watch
```
## Authors
- [Joe Lewis](https://github.com/joelewis)
## Pending Tasks
`grep` the repository for "TODO:"
## ISSUES & FEEDBACK
Use Github Issues to file requests and bugs.
## License
MIT License