Reference manual

This is the reference manual for the ProseMirror rich text editor. It lists and describes the full public API exported by the library.

For more introductory material, please see the guides.

ProseMirror is distributed as a set of JavaScript modules. This reference manual describes the exported API per module. So if you want to use something from the edit module, you have to import it from there.

var edit = require("prosemirror/dist/edit")
var editor = new edit.ProseMirror()

Or in ES6 syntax:

import {ProseMirror} from "prosemirror/dist/edit"
let editor = new ProseMirror()

Note that the content of the dist directory only exists in a built version of code. If you are getting it from npm, you should be fine. If you manually cloned the git repository, you'll need to npm install inside of it first.

module edit

This module implements the ProseMirror editor. It contains functionality related to editing, selection, and integration with the browser. ProseMirror is the class you'll want to instantiate and interact with when using the editor.

Options

schema: Schema πŸ“„

The schema that the editor's document should use. Will default to the schema of the doc option, if that is given.

doc: Node πŸ“„

The starting document.

place: ?union<DOMNode, fn(DOMNode)> πŸ“„

Determines the placement of the editor in the page. When null, the editor is not placed. When a DOM node is given, the editor is appended to that node. When a function is given, it is called with the editor's wrapping DOM node, and is expected to place it into the document.

historyDepth: number πŸ“„

The amount of history events that are collected before the oldest events are discarded. Defaults to 100.

historyEventDelay: number πŸ“„

The amount of milliseconds that must pass between changes to start a new history event. Defaults to 500.

scrollThreshold: number πŸ“„

The minimum distance to keep between the position of document changes and the editor bounding rectangle before scrolling the view. Defaults to 0.

scrollMargin: number πŸ“„

Determines how far to scroll when the scroll threshold is surpassed. Defaults to 5.

keymap: Keymap πŸ“„

Sets the base keymap for the editor. Defaults to baseKeymap.

label: ?string πŸ“„

The label of the editor. When set, the editable DOM node gets an aria-label attribute with this value.

translate(string) β†’Β string πŸ“„

Optional function to translate strings such as menu labels and prompts. When set, should be a function that takes a string as argument and returns a string, i.e. :: (string) β†’ string

plugins: [Plugin] πŸ“„

A set of plugins to enable when the editor is initialized. Defaults to the empty array.

class ProseMirror πŸ“„

This is the class used to represent instances of the editor. A ProseMirror editor holds a document and a selection, and displays an editable surface representing that document in the browser document.

Constructor

new ProseMirror(opts:Β Object) πŸ“„

Construct a new editor from a set of options and, if it has a place option, add it to the document.

Properties

schema: Schema πŸ“„

The schema for this editor's document.

content: DOMNode πŸ“„

The editable DOM node containing the document.

wrapper: DOMNode πŸ“„

The outer DOM element of the editor.

on: Object<Subscription> πŸ“„

A wrapper object containing the various event subscriptions exposed by an editor instance.

change: Subscription<fn()> πŸ“„

Dispatched when the document has changed. See setDoc and transform for more specific change-related events.

selectionChange: Subscription<fn()> πŸ“„

Indicates that the editor's selection has changed.

textInput: Subscription<fn(text:Β string)> πŸ“„

Dispatched when the user types text into the editor.

beforeSetDoc: Subscription<fn(doc:Β Node, selection:Β Selection)> πŸ“„

Dispatched when setDoc is called, before the document is actually updated.

setDoc: Subscription<fn(doc:Β Node, selection:Β Selection)> πŸ“„

Dispatched when setDoc is called, after the document is updated.

interaction: Subscription<fn()> πŸ“„

Dispatched when the user interacts with the editor, for example by clicking on it or pressing a key while it is focused. Mostly useful for closing or resetting transient UI state such as open menus.

focus: Subscription<fn()> πŸ“„

Dispatched when the editor gains focus.

blur: Subscription<fn()> πŸ“„

Dispatched when the editor loses focus.

click: StoppableSubscription<fn(pos:Β number)> πŸ“„

Dispatched when the editor is clicked. Return a truthy value to indicate that the click was handled, and no further action needs to be taken.

clickOn: StoppableSubscription<fn(pos:Β number, node:Β Node, nodePos:Β number)> πŸ“„

Dispatched for every node around a click in the editor, before click is dispatched, from inner to outer nodes. pos is the position neares to the click, nodePos is the position directly in front of node.

doubleClick: StoppableSubscription<fn(pos:Β number)> πŸ“„

Dispatched when the editor is double-clicked.

doubleClickOn: StoppableSubscription<fn(pos:Β number, node:Β Node, nodePos:Β number)> πŸ“„

Dispatched for every node around a double click in the editor, before doubleClick is dispatched.

contextMenu: StoppableSubscription<fn(pos:Β number, node:Β Node)> πŸ“„

Dispatched when the context menu is opened on the editor. Return a truthy value to indicate that you handled the event.

transformPasted: PipelineSubscription<fn(slice:Β Slice) β†’Β Slice> πŸ“„

Dispatched when something is pasted or dragged into the editor. The given slice represents the pasted content, and your handler can return a modified version to manipulate it before it is inserted into the document.

transformPastedText: PipelineSubscription<fn(text:Β string) β†’Β string> πŸ“„

Dispatched when plain text is pasted. Handlers must return the given string or a transformed version of it.

transformPastedHTML: PipelineSubscription<fn(html:Β string) β†’Β string> πŸ“„

Dispatched when html content is pasted or dragged into the editor. Handlers must return the given string or a transformed version of it.

transform: Subscription<fn(transform:Β Transform, selectionBeforeTransform:Β Selection, options:Β Object)> πŸ“„

Signals that a (non-empty) transformation has been aplied to the editor. Passes the Transform, the selection before the transform, and the options given to apply as arguments to the handler.

beforeTransform: Subscription<fn(transform:Β Transform, options:Β Object)> πŸ“„

Indicates that the given transform is about to be applied. The handler may add additional steps to the transform, but it it not allowed to interfere with the editor's state.

filterTransform: StoppableSubscription<fn(transform:Β Transform)> πŸ“„

Dispatched before a transform (applied without filter: false) is applied. The handler can return a truthy value to cancel the transform.

flushing: Subscription<fn()> πŸ“„

Dispatched when the editor is about to flush an update to the DOM.

flush: Subscription<fn()> πŸ“„

Dispatched when the editor has finished flushing an update to the DOM.

draw: Subscription<fn()> πŸ“„

Dispatched when the editor redrew its document in the DOM.

activeMarkChange: Subscription<fn()> πŸ“„

Dispatched when the set of active marks changes.

domDrop: StoppableSubscription<fn(DOMEvent)> πŸ“„

Dispatched when a DOM drop event happens on the editor. Handlers may declare the event as being handled by calling preventDefault on it or returning a truthy value.

selection: Selection πŸ“„

Get the current selection.

doc: Node πŸ“„

The current document.

history: History πŸ“„

The edit history for the editor.

tr: EditorTransform πŸ“„

Create an editor- and selection-aware Transform object for this editor.

Methods

getOption(name:Β string) β†’Β any πŸ“„

Get the value of the given option.

setTextSelection(anchor:Β number, head:Β ?number = anchor) πŸ“„

Set the selection to a text selection from anchor to head, or, if head is null, a cursor selection at anchor.

setNodeSelection(pos:Β number) πŸ“„

Set the selection to a node selection on the node after pos.

setSelection(selection:Β Selection) πŸ“„

Set the selection to the given selection object.

setDoc(doc:Β Node, sel:Β ?Selection) πŸ“„

Set the editor's content, and optionally include a new selection.

apply(transform:Β Transform, options:Β ?Object = nullOptions) β†’Β Transform πŸ“„

Apply a transformation (which you might want to create with the tr getter) to the document in the editor. The following options are supported:

scrollIntoView: ?bool
When true, scroll the selection into view on the next redraw.
selection: ?Selection
A new selection to set after the transformation is applied. If transform is an EditorTransform, this will default to that object's current selection. If no selection is provided, the new selection is determined by mapping the existing selection through the transform.
filter: ?bool
When set to false, suppresses the ability of the filterTransform event to cancel this transform.

Returns the transform itself.

flush() β†’Β bool πŸ“„

Flush any pending changes to the DOM. When the document, selection, or marked ranges in an editor change, the DOM isn't updated immediately, but rather scheduled to be updated the next time the browser redraws the screen. This method can be used to force this to happen immediately. It can be useful when you, for example, want to measure where on the screen a part of the document ends up, immediately after changing the document.

Returns true when it updated the document DOM.

addKeymap(map:Β Keymap, priority:Β ?number = 0) πŸ“„

Add a keymap to the editor. Keymaps added in this way are queried before the base keymap. The priority parameter can be used to control when they are queried relative to other maps added like this. Maps with a higher priority get queried first.

removeKeymap(map:Β union<string, Keymap>) πŸ“„

Remove the given keymap, or the keymap with the given name, from the editor.

markRange(from:Β number, to:Β number, options:Β ?Object) β†’Β MarkedRange πŸ“„

Create a marked range between the given positions. Marked ranges β€œtrack” the part of the document they point toβ€”as the document changes, they are updated to move, grow, and shrink along with their content.

The options parameter may be an object containing these properties:

inclusiveLeft: bool = false
Whether the left side of the range is inclusive. When it is, content inserted at that point will become part of the range. When not, it will be outside of the range.
inclusiveRight: bool = false
Whether the right side of the range is inclusive.
removeWhenEmpty: bool = true
Whether the range should be forgotten when it becomes empty (because all of its content was deleted).
className: string
A CSS class to add to the inline content that is part of this range.
onRemove: fn(number, number)
When given, this function will be called when the range is removed from the editor.
removeRange(range:Β MarkedRange) πŸ“„

Remove the given range from the editor.

activeMarks() β†’Β [Mark] πŸ“„

Get the marks at the cursor. By default, this yields the marks associated with the content at the cursor, as per Node.marksAt. But if the set of active marks was updated with addActiveMark or removeActiveMark, the updated set is returned.

addActiveMark(mark:Β Mark) πŸ“„

Add a mark to the set of overridden active marks that will be applied to subsequently typed text. Does not do anything when the selection isn't collapsed.

removeActiveMark(markType:Β MarkType) πŸ“„

Remove any mark of the given type from the set of overidden active marks.

focus() πŸ“„

Give the editor focus.

hasFocus() β†’Β bool πŸ“„

Query whether the editor has focus.

posAtCoords(coords:Β {top:Β number, left:Β number}) β†’Β ?number πŸ“„

If the given coordinates (which should be relative to the top left corner of the windowβ€”not the page) fall within the editable content, this method will return the document position that corresponds to those coordinates.

contextAtCoords(coords:Β {top:Β number, left:Β number}) β†’Β ?{pos:Β number, inside:Β [{pos:Β number, node:Β Node}]} πŸ“„

If the given coordinates fall within the editable content, this method will return the document position that corresponds to those coordinates, along with a stack of nodes and their positions (excluding the top node) that the coordinates fall into.

coordsAtPos(pos:Β number) β†’Β {top:Β number, left:Β number, bottom:Β number} πŸ“„

Find the screen coordinates (relative to top left corner of the window) of the given document position.

scrollIntoView(pos:Β ?number = null) πŸ“„

Scroll the given position, or the cursor position if pos isn't given, into view.

translate(string:Β string) β†’Β string πŸ“„

Return a translated string, if a translate function has been supplied, or the original string.

scheduleDOMUpdate(f:Β fn() β†’Β ?fn() β†’Β ?fn()) πŸ“„

Schedule a DOM update function to be called either the next time the editor is flushed, or if no flush happens immediately, after 200 milliseconds. This is used to synchronize DOM updates and read to prevent DOM layout thrashing.

Often, your updates will need to both read and write from the DOM. To schedule such access in lockstep with other modules, the function you give can return another function, which may return another function, and so on. The first call should write to the DOM, and not read. If a read needs to happen, that should be done in the function returned from the first call. If that has to be followed by another write, that should be done in a function returned from the second function, and so on.

unscheduleDOMUpdate(f:Β fn() β†’Β ?fn() β†’Β ?fn()) πŸ“„

Cancel an update scheduled with scheduleDOMUpdate. Calling this with a function that is not actually scheduled is harmless.

updateScheduler(subscriptions:Β [Subscription], start:Β fn() β†’Β ?fn()) β†’Β UpdateScheduler πŸ“„

Creates an update scheduler for this editor. subscriptions should be an array of subscriptions to listen for. start should be a function as expected by scheduleDOMUpdate.

class Selection πŸ“„

An editor selection. Can be one of two selection types: TextSelection or NodeSelection. Both have the properties listed here, but also contain more information (such as the selected node or the head and anchor).

Properties

from: number πŸ“„

The left bound of the selection.

to: number πŸ“„

The right bound of the selection.

$from: ResolvedPos πŸ“„

The resolved left bound of the selection

$to: ResolvedPos πŸ“„

The resolved right bound of the selection

empty: bool πŸ“„

True if the selection is an empty text selection (head an anchor are the same).

Methods

eq(other:Β Selection) β†’Β bool πŸ“„

Test whether the selection is the same as another selection.

map(doc:Β Node, mapping:Β Mappable) β†’Β Selection πŸ“„

Map this selection through a mappable thing. doc should be the new document, to which we are mapping.

class TextSelection πŸ“„

Extends Selection.

A text selection represents a classical editor selection, with a head (the moving side) and anchor (immobile side), both of which point into textblock nodes. It can be empty (a regular cursor position).

Constructor

new TextSelection($anchor:Β ResolvedPos, $head:Β ?ResolvedPos = $anchor) πŸ“„

Construct a text selection. When head is not given, it defaults to anchor.

Properties

anchor: number πŸ“„

The selection's immobile side (does not move when pressing shift-arrow).

head: number πŸ“„

The selection's mobile side (the side that moves when pressing shift-arrow).

$anchor: ResolvedPos πŸ“„

The resolved anchor of the selection.

$head: ResolvedPos πŸ“„

The resolved head of the selection.

class NodeSelection πŸ“„

Extends Selection.

A node selection is a selection that points at a single node. All nodes marked selectable can be the target of a node selection. In such an object, from and to point directly before and after the selected node.

Constructor

new NodeSelection($from:Β ResolvedPos) πŸ“„

Create a node selection. Does not verify the validity of its argument. Use ProseMirror.setNodeSelection for an easier, error-checking way to create a node selection.

Properties

node: Node πŸ“„

The selected node.

class Plugin πŸ“„

A plugin is a piece of functionality that can be attached to a ProseMirror instance. It may do something like show a menu or wire in collaborative editing. The plugin object is the interface to enabling and disabling the plugin, and for those where this is relevant, for accessing its state.

Constructor

new Plugin(State:Β constructor, options:Β ?Object) πŸ“„

Create a plugin object for the given state class. If desired, you can pass a collection of options. When initializing the plugin, it will receive the ProseMirror instance and the options as arguments to its constructor.

Methods

get(pm:Β ProseMirror) β†’Β ?any πŸ“„

Return the plugin state for the given editor, if any.

attach(pm:Β ProseMirror) β†’Β any πŸ“„

Initialize the plugin for the given editor. If it was already enabled, this throws an error.

detach(pm:Β ProseMirror) πŸ“„

Disable the plugin in the given editor. If the state has a detach method, that will be called with the editor as argument, to give it a chance to clean up.

ensure(pm:Β ProseMirror) β†’Β any πŸ“„

Get the plugin state for an editor. Initializes the plugin if it wasn't already active.

config(options:Β ?Object) β†’Β Plugin πŸ“„

Configure the plugin. The given options will be combined with the existing (default) options, with the newly provided ones taking precedence. Returns a new plugin object with the new configuration.

class History πŸ“„

An undo/redo history manager for an editor instance.

Properties

undoDepth: number πŸ“„

The amount of undoable events available.

redoDepth: number πŸ“„

The amount of redoable events available.

Methods

undo() β†’Β bool πŸ“„

Undo one history event. The return value indicates whether anything was actually undone. Note that in a collaborative context, or when changes are applied without adding them to the history, it is possible for undoDepth to have a positive value, but this method to still return false, when non-history changes overwrote all remaining changes in the history.

redo() β†’Β bool πŸ“„

Redo one history event. The return value indicates whether anything was actually redone.

getVersion() β†’Β Object πŸ“„

Get the current β€˜version’ of the editor content. This can be used to later check whether anything changed, or to roll back to this version.

isAtVersion(version:Β Object) β†’Β bool πŸ“„

Returns true when the editor history is in the state that it was when the given version was recorded. That means either no changes were made, or changes were done/undone and then undone/redone again.

backToVersion(version:Β Object) β†’Β bool πŸ“„

Rolls back all changes made since the given version was recorded. Returns false if that version was no longer found in the history, and thus the action could not be completed.

class MarkedRange πŸ“„

A marked range as created by markRange.

Properties

from: ?number πŸ“„

The current start position of the range. Updated whenever the editor's document is changed. Set to null when the marked range is removed.

to: ?number πŸ“„

The current end position of the range. Updated whenever the editor's document is changed. Set to null when the marked range is removed.

class EditorTransform πŸ“„

Extends Transform.

A selection-aware extension of Transform. Use ProseMirror.tr to create an instance.

Properties

selection: Selection πŸ“„

The transform's current selection. This defaults to the editor selection mapped through the steps in this transform, but can be overwritten with setSelection.

Methods

apply(options:Β ?Object) β†’Β EditorTransform πŸ“„

Apply the transformation. Returns the transform, or false it is was empty.

applyAndScroll() β†’Β EditorTransform πŸ“„

Apply this transform with a {scrollIntoView: true} option.

setSelection(selection:Β Selection) β†’Β EditorTransform πŸ“„

Update the transform's current selection. This will determine the selection that the editor gets when the transform is applied.

replaceSelection(node:Β ?Node, inheritMarks:Β ?bool) β†’Β EditorTransform πŸ“„

Replace the selection with the given node, or delete it if node is null. When inheritMarks is true and the node is an inline node, it inherits the marks from the place where it is inserted.

deleteSelection() β†’Β EditorTransform πŸ“„

Delete the selection.

typeText(text:Β string) β†’Β EditorTransform πŸ“„

Replace the selection with a text node containing the given string.

class UpdateScheduler πŸ“„

Helper for scheduling updates whenever any of a series of events happen. Created with the updateScheduler method.

Methods

detach() πŸ“„

Detach the event handlers registered by this scheduler.

force() πŸ“„

Force an update. Note that if the editor has scheduled a flush, the update is still delayed until the flush occurs.

Constants

commands: Object πŸ“„

This object contains a number of β€˜commandsβ€˜, functions that take a ProseMirror instance and try to perform some action on it, returning false if they don't apply. These are used to bind keys to, and to define menu items.

Most of the command functions defined here take a second, optional, boolean parameter. This can be set to false to do a β€˜dry run’, where the function won't take any actual action, but will return information about whether it applies.

chainCommands(...commands:Β [fn(ProseMirror, ?bool) β†’Β bool]) β†’Β fn(ProseMirror, ?bool) β†’Β bool πŸ“„

Combine a number of command functions into a single function (which calls them one by one until one returns something other than false).

deleteSelection(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Delete the selection, if there is one.

joinBackward(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

If the selection is empty and at the start of a textblock, move that block closer to the block before it, by lifting it out of its parent or, if it has no parent it doesn't share with the node before it, moving it into a parent of that node, or joining it with that.

joinForward(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

If the selection is empty and the cursor is at the end of a textblock, move the node after it closer to the node with the cursor (lifting it out of parents that aren't shared, moving it into parents of the cursor block, or joining the two when they are siblings).

deleteCharBefore(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Delete the character before the cursor, if the selection is empty and the cursor isn't at the start of a textblock.

deleteWordBefore(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Delete the word before the cursor, if the selection is empty and the cursor isn't at the start of a textblock.

deleteCharAfter(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Delete the character after the cursor, if the selection is empty and the cursor isn't at the end of its textblock.

deleteWordAfter(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Delete the word after the cursor, if the selection is empty and the cursor isn't at the end of a textblock.

joinUp(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Join the selected block or, if there is a text selection, the closest ancestor block of the selection that can be joined, with the sibling above it.

joinDown(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Join the selected block, or the closest ancestor of the selection that can be joined, with the sibling after it.

lift(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Lift the selected block, or the closest ancestor block of the selection that can be lifted, out of its parent node.

newlineInCode(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

If the selection is in a node whose type has a truthy isCode property, replace the selection with a newline character.

createParagraphNear(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

If a block node is selected, create an empty paragraph before (if it is its parent's first child) or after it.

liftEmptyBlock(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

If the cursor is in an empty textblock that can be lifted, lift the block.

splitBlock(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Split the parent block of the selection. If the selection is a text selection, delete it.

selectParentNode(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Move the selection to the node wrapping the current selection, if any. (Will not select the document node.)

undo(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Undo the most recent change event, if any.

redo(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Redo the most recently undone change event, if any.

wrapIn(nodeType:Β NodeType, attrs:Β ?Object) β†’Β fn(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Wrap the selection in a node of the given type with the given attributes. When apply is false, just tell whether this is possible, without performing any action.

setBlockType(nodeType:Β NodeType, attrs:Β ?Object) β†’Β fn(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Try to the textblock around the selection to the given node type with the given attributes. Return true when this is possible. If apply is false, just report whether the change is possible, don't perform any action.

wrapInList(nodeType:Β NodeType, attrs:Β ?Object) β†’Β fn(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Returns a command function that wraps the selection in a list with the given type an attributes. If apply is false, only return a value to indicate whether this is possible, but don't actually perform the change.

splitListItem(nodeType:Β NodeType) β†’Β fn(pm:Β ProseMirror) β†’Β bool πŸ“„

Build a command that splits a non-empty textblock at the top level of a list item by also splitting that list item.

liftListItem(nodeType:Β NodeType) β†’Β fn(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Create a command to lift the list item around the selection up into a wrapping list.

sinkListItem(nodeType:Β NodeType) β†’Β fn(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Create a command to sink the list item around the selection down into an inner list.

toggleMark(markType:Β MarkType, attrs:Β ?Object) β†’Β fn(pm:Β ProseMirror, apply:Β ?bool) β†’Β bool πŸ“„

Create a command function that toggles the given mark with the given attributes. Will return false when the current selection doesn't support that mark. If apply is not false, it will remove the mark if any marks of that type exist in the selection, or add it otherwise. If the selection is empty, this applies to the active marks instead of a range of the document.

baseKeymap: Keymap πŸ“„

module model

This module defines ProseMirror's document model, the data structure used to define and inspect content documents. It includes:

This module does not depend on the browser API being available (i.e. you can load it into any JavaScript environment).

class Node πŸ“„

This class represents a node in the tree that makes up a ProseMirror document. So a document is an instance of Node, with children that are also instances of Node.

Nodes are persistent data structures. Instead of changing them, you create new ones with the content you want. Old ones keep pointing at the old document shape. This is made cheaper by sharing structure between the old and new data as much as possible, which a tree shape like this (without back pointers) makes easy.

Never directly mutate the properties of a Node object. See this guide for more information.

Properties

type: NodeType πŸ“„

The type of node that this is.

attrs: Object πŸ“„

An object mapping attribute names to values. The kind of attributes allowed and required are determined by the node type.

content: Fragment πŸ“„

A container holding the node's children.

marks: [Mark] πŸ“„

The marks (things like whether it is emphasized or part of a link) associated with this node.

text: ?string πŸ“„

For text nodes, this contains the node's text content.

nodeSize: number πŸ“„

The size of this node. For text nodes, this is the amount of characters. For leaf nodes, it is one. And for non-leaf nodes, it is the size of the content plus two (the start and end token).

childCount: number πŸ“„

The number of children that the node has.

textContent: string πŸ“„

Concatenates all the text nodes found in this fragment and its children.

firstChild: ?Node πŸ“„

Returns this node's first child, or null if there are no children.

lastChild: ?Node πŸ“„

Returns this node's last child, or null if there are no children.

isBlock: bool πŸ“„

True when this is a block (non-inline node)

isTextblock: bool πŸ“„

True when this is a textblock node, a block node with inline content.

isInline: bool πŸ“„

True when this is an inline node (a text node or a node that can appear among text).

isText: bool πŸ“„

True when this is a text node.

Methods

child(index:Β number) β†’Β Node πŸ“„

Get the child node at the given index. Raises an error when the index is out of range.

maybeChild(index:Β number) β†’Β ?Node πŸ“„

Get the child node at the given index, if it exists.

forEach(f:Β fn(node:Β Node, offset:Β number, index:Β number)) πŸ“„

Call f for every child node, passing the node, its offset into this parent node, and its index.

textBetween(from:Β number, to:Β number, separator:Β ?string) β†’Β string πŸ“„

Get all text between positions from and to. When separator is given, it will be inserted whenever a new block node is started.

eq(other:Β Node) β†’Β bool πŸ“„

Test whether two nodes represent the same content.

sameMarkup(other:Β Node) β†’Β bool πŸ“„

Compare the markup (type, attributes, and marks) of this node to those of another. Returns true if both have the same markup.

hasMarkup(type:Β NodeType, attrs:Β ?Object, marks:Β ?[Mark]) β†’Β bool πŸ“„

Check whether this node's markup correspond to the given type, attributes, and marks.

copy(content:Β ?Fragment = null) β†’Β Node πŸ“„

Create a new node with the same markup as this node, containing the given content (or empty, if no content is given).

mark(marks:Β [Mark]) β†’Β Node πŸ“„

Create a copy of this node, with the given set of marks instead of the node's own marks.

cut(from:Β number, to:Β ?number) β†’Β Node πŸ“„

Create a copy of this node with only the content between the given offsets. If to is not given, it defaults to the end of the node.

slice(from:Β number, to:Β ?number = this.content.size) β†’Β Slice πŸ“„

Cut out the part of the document between the given positions, and return it as a Slice object.

replace(from:Β number, to:Β number, slice:Β Slice) β†’Β Node πŸ“„

Replace the part of the document between the given positions with the given slice. The slice must 'fit', meaning its open sides must be able to connect to the surrounding content, and its content nodes must be valid children for the node they are placed into. If any of this is violated, an error of type ReplaceError is thrown.

nodeAt(pos:Β number) β†’Β ?Node πŸ“„

Find the node after the given position.

childAfter(pos:Β number) β†’Β {node:Β ?Node, index:Β number, offset:Β number} πŸ“„

Find the (direct) child node after the given offset, if any, and return it along with its index and offset relative to this node.

childBefore(pos:Β number) β†’Β {node:Β ?Node, index:Β number, offset:Β number} πŸ“„

Find the (direct) child node before the given offset, if any, and return it along with its index and offset relative to this node.

nodesBetween(from:Β ?number, to:Β ?number, f:Β fn(node:Β Node, pos:Β number, parent:Β Node, index:Β number)) πŸ“„

Iterate over all nodes between the given two positions, calling the callback with the node, its position, its parent node, and its index in that node.

descendants(f:Β fn(node:Β Node, pos:Β number, parent:Β Node)) πŸ“„

Call the given callback for every descendant node.

resolve(pos:Β number) β†’Β ResolvedPos πŸ“„

Resolve the given position in the document, returning an object describing its path through the document.

marksAt(pos:Β number) β†’Β [Mark] πŸ“„

Get the marks at the given position factoring in the surrounding marks' inclusiveLeft and inclusiveRight properties. If the position is at the start of a non-empty node, the marks of the node after it are returned.

rangeHasMark(from:Β ?number, to:Β ?number, type:Β MarkType) β†’Β bool πŸ“„

Test whether a mark of the given type occurs in this document between the two given positions.

toString() β†’Β string πŸ“„

Return a string representation of this node for debugging purposes.

contentMatchAt(index:Β number) β†’Β ContentMatch πŸ“„

Get the content match in this node at the given index.

canReplace(from:Β number, to:Β number, replacement:Β ?Fragment, start:Β ?number, end:Β ?number) β†’Β bool πŸ“„

Test whether replacing the range from to to (by index) with the given replacement fragment (which defaults to the empty fragment) would leave the node's content valid. You can optionally pass start and end indices into the replacement fragment.

canReplaceWith(from:Β number, to:Β number, type:Β NodeType, attrs:Β ?[Mark]) β†’Β bool πŸ“„

Test whether replacing the range from to to (by index) with a node of the given type with the given attributes and marks would be valid.

canAppend(other:Β Node) β†’Β bool πŸ“„

Test whether the given node's content could be appended to this node. If that node is empty, this will only return true if there is at least one node type that can appear in both nodes (to avoid merging completely incompatible nodes).

toJSON() β†’Β Object πŸ“„

Return a JSON-serializeable representation of this node.

toDOM(options:Β ?Object = {}) β†’Β DOMNode πŸ“„

Serialize this node to a DOM node. This can be useful when you need to serialize a part of a document, as opposed to the whole document, but you'll usually want to do doc.content.toDOM() instead.

Static properties

fromJSON(schema:Β Schema, json:Β Object) β†’Β Node πŸ“„

Deserialize a node from its JSON representation.

class ResolvedPos πŸ“„

The usual way to represent positions in a document is with a plain integer. Since those tell you very little about the context of that position, you'll often have to 'resolve' a position to get the context you need. Objects of this class represent such a resolved position, providing various pieces of context information and helper methods.

Throughout this interface, methods that take an optional depth parameter will interpret undefined as this.depth and negative numbers as this.depth + value.

Properties

pos: number πŸ“„

The position that was resolved.

depth: number πŸ“„

The number of levels the parent node is from the root. If this position points directly into the root, it is 0. If it points into a top-level paragraph, 1, and so on.

parentOffset: number πŸ“„

The offset this position has into its parent node.

parent: Node πŸ“„

The parent node that the position points into. Note that even if a position points into a text node, that node is not considered the parentβ€”text nodes are 'flat' in this model.

atNodeBoundary: bool πŸ“„

True if this position points at a node boundary, false if it points into a text node.

nodeAfter: ?Node πŸ“„

Get the node directly after the position, if any. If the position points into a text node, only the part of that node after the position is returned.

nodeBefore: ?Node πŸ“„

Get the node directly before the position, if any. If the position points into a text node, only the part of that node before the position is returned.

Methods

node(depth:Β ?number) β†’Β Node πŸ“„

The ancestor node at the given level. p.node(p.depth) is the same as p.parent.

index(depth:Β ?number) β†’Β number πŸ“„

The index into the ancestor at the given level. If this points at the 3rd node in the 2nd paragraph on the top level, for example, p.index(0) is 2 and p.index(1) is 3.

indexAfter(depth:Β ?number) β†’Β number πŸ“„

The index pointing after this position into the ancestor at the given level.

start(depth:Β ?number) β†’Β number πŸ“„

The (absolute) position at the start of the node at the given level.

end(depth:Β ?number) β†’Β number πŸ“„

The (absolute) position at the end of the node at the given level.

before(depth:Β ?number) β†’Β number πŸ“„

The (absolute) position directly before the node at the given level, or, when level is this.level + 1, the original position.

after(depth:Β ?number) β†’Β number πŸ“„

The (absolute) position directly after the node at the given level, or, when level is this.level + 1, the original position.

sameDepth(other:Β ResolvedPos) β†’Β number πŸ“„

The depth up to which this position and the other share the same parent nodes.

blockRange(other:Β ?ResolvedPos = this, pred:Β ?fn(Node) β†’Β bool) β†’Β ?NodeRange πŸ“„

Returns a range based on the place where this position and the given position diverge around block content. If both point into the same textblock, for example, a range around that textblock will be returned. If they point into different blocks, the range around those blocks or their ancestors in their common ancestor is returned. You can pass in an optional predicate that will be called with a parent node to see if a range into that parent is acceptable.

sameParent(other:Β ResolvedPos) β†’Β bool πŸ“„

Query whether the given position shares the same parent node.

class NodeRange πŸ“„

Represents a flat range of content.

Properties

$from: ResolvedPos πŸ“„

A resolved position along the start of the content. May have a depth greater than this object's depth property, since these are the positions that were used to compute the range, not re-resolved positions directly at its boundaries.

$to: ResolvedPos πŸ“„

A position along the end of the content. See caveat for from.

depth: number πŸ“„

The depth of the node that this range points into.

start: number πŸ“„

The position at the start of the range.

end: number πŸ“„

The position at the end of the range.

parent: Node πŸ“„

The parent node that the range points into.

startIndex: number πŸ“„

The start index of the range in the parent node.

endIndex: number πŸ“„

The end index of the range in the parent node.

class Fragment πŸ“„

Fragment is the type used to represent a node's collection of child nodes.

Fragments are persistent data structures. That means you should not mutate them or their content, but create new instances whenever needed. The API tries to make this easy.

Properties

firstChild: ?Node πŸ“„

The first child of the fragment, or null if it is empty.

lastChild: ?Node πŸ“„

The last child of the fragment, or null if it is empty.

childCount: number πŸ“„

The number of child nodes in this fragment.

Methods

toString() β†’Β string πŸ“„

Return a debugging string that describes this fragment.

cut(from:Β number, to:Β ?number) β†’Β Fragment πŸ“„

Cut out the sub-fragment between the two given positions.

append(other:Β Fragment) β†’Β Fragment πŸ“„

Create a new fragment containing the content of this fragment and other.

replaceChild(index:Β number, node:Β Node) β†’Β Fragment πŸ“„

Create a new fragment in which the node at the given index is replaced by the given node.

toJSON() β†’Β ?Object πŸ“„

Create a JSON-serializeable representation of this fragment.

eq(other:Β Fragment) β†’Β bool πŸ“„

Compare this fragment to another one.

child(index:Β number) β†’Β Node πŸ“„

Get the child node at the given index. Raise an error when the index is out of range.

maybeChild(index:Β number) β†’Β ?Node πŸ“„

Get the child node at the given index, if it exists.

forEach(f:Β fn(node:Β Node, offset:Β number, index:Β number)) πŸ“„

Call f for every child node, passing the node, its offset into this parent node, and its index.

findDiffStart(other:Β Fragment) β†’Β ?number πŸ“„

Find the first position at which this fragment and another fragment differ, or null if they are the same.

findDiffEnd(other:Β Node) β†’Β ?{a:Β number, b:Β number} πŸ“„

Find the first position, searching from the end, at which this fragment and the given fragment differ, or null if they are the same. Since this position will not be the same in both nodes, an object with two separate positions is returned.

toDOM(options:Β ?Object = {}) β†’Β DOMFragment πŸ“„

Serialize the content of this fragment to a DOM fragment. When not in the browser, the document option, containing a DOM document, should be passed so that the serialize can create nodes.

To specify rendering behavior for your own node and mark types, define a toDOM method on them.

Static properties

fromJSON(schema:Β Schema, value:Β ?Object) β†’Β Fragment πŸ“„

Deserialize a fragment from its JSON representation.

fromArray(array:Β [Node]) β†’Β Fragment πŸ“„

Build a fragment from an array of nodes. Ensures that adjacent text nodes with the same style are joined together.

from(nodes:Β ?union<Fragment, Node, [Node]>) β†’Β Fragment πŸ“„

Create a fragment from something that can be interpreted as a set of nodes. For null, it returns the empty fragment. For a fragment, the fragment itself. For a node or array of nodes, a fragment containing those nodes.

empty: Fragment πŸ“„

An empty fragment. Intended to be reused whenever a node doesn't contain anything (rather than allocating a new empty fragment for each leaf node).

class ReplaceError πŸ“„

Extends ProseMirrorError.

Error type raised by Node.replace when given an invalid replacement.

class Slice πŸ“„

A slice represents a piece cut out of a larger document. It stores not only a fragment, but also the depth up to which nodes on both side are 'open' / cut through.

Constructor

new Slice(content:Β Fragment, openLeft:Β number, openRight:Β number, possibleParent:Β ?Node) πŸ“„

Properties

content: Fragment πŸ“„

The slice's content nodes.

openLeft: number πŸ“„

The open depth at the start.

openRight: number πŸ“„

The open depth at the end.

size: number πŸ“„

The size this slice would add when inserted into a document.

Methods

toJSON() β†’Β ?Object πŸ“„

Convert a slice to a JSON-serializable representation.

Static properties

fromJSON(schema:Β Schema, json:Β ?Object) β†’Β Slice πŸ“„

Deserialize a slice from its JSON representation.

empty: Slice πŸ“„

The empty slice.

class Mark πŸ“„

A mark is a piece of information that can be attached to a node, such as it being emphasized, in code font, or a link. It has a type and optionally a set of attributes that provide further information (such as the target of the link). Marks are created through a Schema, which controls which types exist and which attributes they have.

Properties

type: MarkType πŸ“„

The type of this mark.

attrs: Object πŸ“„

The attributes associated with this mark.

Methods

toJSON() β†’Β Object πŸ“„

Convert this mark to a JSON-serializeable representation.

addToSet(set:Β [Mark]) β†’Β [Mark] πŸ“„

Given a set of marks, create a new set which contains this one as well, in the right position. If this mark is already in the set, the set itself is returned. If a mark of this type with different attributes is already in the set, a set in which it is replaced by this one is returned.

removeFromSet(set:Β [Mark]) β†’Β [Mark] πŸ“„

Remove this mark from the given set, returning a new set. If this mark is not in the set, the set itself is returned.

isInSet(set:Β [Mark]) β†’Β bool πŸ“„

Test whether this mark is in the given set of marks.

eq(other:Β Mark) β†’Β bool πŸ“„

Test whether this mark has the same type and attributes as another mark.

Static properties

sameSet(a:Β [Mark], b:Β [Mark]) β†’Β bool πŸ“„

Test whether two sets of marks are identical.

setFrom(marks:Β ?union<Mark, [Mark]>) β†’Β [Mark] πŸ“„

Create a properly sorted mark set from null, a single mark, or an unsorted array of marks.

none: [Mark] πŸ“„

The empty set of marks.

class NodeType πŸ“„

Node types are objects allocated once per Schema and used to tag Node instances with a type. They are instances of sub-types of this class, and contain information about the node type (its name, its allowed attributes, methods for serializing it to various formats, information to guide deserialization, and so on).

Properties

name: string πŸ“„

The name the node type has in this schema.

schema: Schema πŸ“„

A link back to the Schema the node type belongs to.

attrs: Object<Attribute> πŸ“„

The attributes for this node type.

isBlock: bool πŸ“„

True if this is a block type.

isTextblock: bool πŸ“„

True if this is a textblock type, a block that contains inline content.

isInline: bool πŸ“„

True if this is an inline type.

isText: bool πŸ“„

True if this is the text node type.

isLeaf: bool πŸ“„

True for node types that allow no content.

selectable: bool πŸ“„

Controls whether nodes of this type can be selected (as a node selection).

draggable: bool πŸ“„

Determines whether nodes of this type can be dragged. Enabling it causes ProseMirror to set a draggable attribute on its DOM representation, and to put its HTML serialization into the drag event's data transfer when dragged.

matchDOMTag: Object<union<ParseSpec, fn(DOMNode) β†’Β union<bool, ParseSpec>>> πŸ“„

Defines the way nodes of this type are parsed. Should, if present, contain an object mapping CSS selectors (such as "p" for <p> tags, or "div[data-type=foo]" for <div> tags with a specific attribute) to parse specs or functions that, when given a DOM node, return either false or a parse spec.

Methods

create(attrs:Β ?Object, content:Β ?union<Fragment, Node, [Node]>, marks:Β ?[Mark]) β†’Β Node πŸ“„

Create a Node of this type. The given attributes are checked and defaulted (you can pass null to use the type's defaults entirely, if no required attributes exist). content may be a Fragment, a node, an array of nodes, or null. Similarly marks may be null to default to the empty set of marks.

createChecked(attrs:Β ?Object, content:Β ?union<Fragment, Node, [Node]>, marks:Β ?[Mark]) β†’Β Node πŸ“„

Like create, but check the given content against the node type's content restrictions, and throw an error if it doesn't match.

createAndFill(attrs:Β ?Object, content:Β ?union<Fragment, Node, [Node]>, marks:Β ?[Mark]) β†’Β ?Node πŸ“„

Like create, but see if it is necessary to add nodes to the start or end of the given fragment to make it fit the node. If no fitting wrapping can be found, return null. Note that, due to the fact that required nodes can always be created, this will always succeed if you pass null or Fragment.empty as content.

validContent(content:Β Fragment, attrs:Β ?Object) β†’Β bool πŸ“„

Returns true if the given fragment is valid content for this node type with the given attributes.

toDOM(_:Β Node) β†’Β DOMOutputSpec πŸ“„

Defines the way a node of this type should be serialized to DOM/HTML. Should return an array structure that describes the resulting DOM structure, with an optional number zero (β€œhole”) in it to indicate where the node's content should be inserted.

class Block πŸ“„

Extends NodeType.

Base type for block nodetypes.

class Inline πŸ“„

Extends NodeType.

Base type for inline node types.

class Text πŸ“„

Extends Inline.

The text node type.

class Attribute πŸ“„

Attributes are named values associated with nodes and marks. Each node type or mark type has a fixed set of attributes, which instances of this class are used to control. Attribute values must be JSON-serializable.

Constructor

new Attribute(options:Β ?Object = {}) πŸ“„

Create an attribute. options is an object containing the settings for the attributes. The following settings are supported:

default: ?any
The default value for this attribute, to choose when no explicit value is provided.
compute: ?() β†’ any
A function that computes a default value for the attribute.

Attributes that have no default or compute property must be provided whenever a node or mark of a type that has them is created.

class MarkType πŸ“„

Like nodes, marks (which are associated with nodes to signify things like emphasis or being part of a link) are tagged with type objects, which are instantiated once per Schema.

Properties

name: string πŸ“„

The name of the mark type.

schema: Schema πŸ“„

The schema that this mark type instance is part of.

inclusiveRight: bool πŸ“„

Whether this mark should be active when the cursor is positioned at the end of the mark.

matchDOMTag: Object<union<ParseSpec, fn(DOMNode) β†’Β union<bool, ParseSpec>>> πŸ“„

Defines the way marks of this type are parsed. Works just like NodeType.matchTag, but produces marks rather than nodes.

matchDOMStyle: Object<union<?Object, fn(string) β†’Β union<bool, ?Object>>> πŸ“„

Defines the way DOM styles are mapped to marks of this type. Should contain an object mapping CSS property names, as found in inline styles, to either attributes for this mark (null for default attributes), or a function mapping the style's value to either a set of attributes or false to indicate that the style does not match.

Methods

create(attrs:Β ?Object) β†’Β Mark πŸ“„

Create a mark of this type. attrs may be null or an object containing only some of the mark's attributes. The others, if they have defaults, will be added.

removeFromSet(set:Β [Mark]) β†’Β [Mark] πŸ“„

When there is a mark of this type in the given set, a new set without it is returned. Otherwise, the input set is returned.

isInSet(set:Β [Mark]) β†’Β ?Mark πŸ“„

Tests whether there is a mark of this type in the given set.

toDOM(mark:Β Mark) β†’Β DOMOutputSpec πŸ“„

Defines the way marks of this type should be serialized to DOM/HTML.

interface SchemaSpec

An object describing a schema, as passed to the Schema constructor.

nodes: union<Object<NodeSpec>, OrderedMap<NodeSpec>> πŸ“„

The node types in this schema. Maps names to NodeSpec objects describing the node to be associated with that name. Their order is significant

marks: ?union<Object<constructor<MarkType>>, OrderedMap<constructor<MarkType>>> πŸ“„

The mark types that exist in this schema.

interface NodeSpec

type: constructor<NodeType> πŸ“„

The NodeType class to be used for this node.

content: ?string πŸ“„

The content expression for this node, as described in the schema guide. When not given, the node does not allow any content.

group: ?string πŸ“„

The group or space-separated groups to which this node belongs, as referred to in the content expressions for the schema.

class Schema πŸ“„

Each document is based on a single schema, which provides the node and mark types that it is made up of (which, in turn, determine the structure it is allowed to have).

Constructor

new Schema(spec:Β SchemaSpec, data:Β ?any) πŸ“„

Construct a schema from a specification.

Properties

nodeSpec: OrderedMap<NodeSpec> πŸ“„

The node specs that the schema is based on.

markSpec: OrderedMap<constructor<MarkType>> πŸ“„

The mark spec that the schema is based on.

data: any πŸ“„

A generic field that you can use (by passing a value to the constructor) to store arbitrary data or references in your schema object, for use by node- or mark- methods.

nodes: Object<NodeType> πŸ“„

An object mapping the schema's node names to node type objects.

marks: Object<MarkType> πŸ“„

A map from mark names to mark type objects.

cached: Object πŸ“„

An object for storing whatever values modules may want to compute and cache per schema. (If you want to store something in it, try to use property names unlikely to clash.)

Methods

node(type:Β union<string, NodeType>, attrs:Β ?Object, content:Β ?union<Fragment, Node, [Node]>, marks:Β ?[Mark]) β†’Β Node πŸ“„

Create a node in this schema. The type may be a string or a NodeType instance. Attributes will be extended with defaults, content may be a Fragment, null, a Node, or an array of nodes.

When creating a text node, content should be a string and is interpreted as the node's text.

This method is bound to the Schema, meaning you don't have to call it as a method, but can pass it to higher-order functions and such.

text(text:Β string, marks:Β ?[Mark]) β†’Β Node πŸ“„

Create a text node in the schema. This method is bound to the Schema. Empty text nodes are not allowed.

mark(name:Β string, attrs:Β ?Object) β†’Β Mark πŸ“„

Create a mark with the named type

nodeFromJSON(json:Β Object) β†’Β Node πŸ“„

Deserialize a node from its JSON representation. This method is bound.

markFromJSON(json:Β Object) β†’Β Mark πŸ“„

Deserialize a mark from its JSON representation. This method is bound.

nodeType(name:Β string) β†’Β NodeType πŸ“„

Get the NodeType associated with the given name in this schema, or raise an error if it does not exist.

parseDOM(dom:Β DOMNode, options:Β ?Object = {}) β†’Β Node πŸ“„

Parse a document from the content of a DOM node. To provide an explicit parent document (for example, when not in a browser window environment, where we simply use the global document), pass it as the document property of options.

class ContentMatch πŸ“„

Represents a partial match of a node type's content expression, and can be used to find out whether further content matches here, and whether a given position is a valid end of the parent node.

Methods

matchNode(node:Β Node) β†’Β ?ContentMatch πŸ“„

Match a node, returning a new match after the node if successful.

matchType(type:Β NodeType, attrs:Β ?Object, marks:Β ?[Mark] = Mark.none) β†’Β ?ContentMatch πŸ“„

Match a node type and marks, returning an match after that node if successful.

matchFragment(fragment:Β Fragment, from:Β ?number = 0, to:Β ?number = fragment.childCount) β†’Β ?union<ContentMatch, bool> πŸ“„

Try to match a fragment. Returns a new match when successful, null when it ran into a required element it couldn't fit, and false if it reached the end of the expression without matching all nodes.

matchToEnd(fragment:Β Fragment, start:Β ?number, end:Β ?number) β†’Β bool πŸ“„

Returns true only if the fragment matches here, and reaches all the way to the end of the content expression.

validEnd() β†’Β bool πŸ“„

Returns true if this position represents a valid end of the expression (no required content follows after it).

fillBefore(after:Β Fragment, toEnd:Β bool, startIndex:Β ?number) β†’Β ?Fragment πŸ“„

Try to match the given fragment, and if that fails, see if it can be made to match by inserting nodes in front of it. When successful, return a fragment of inserted nodes (which may be empty if nothing had to be inserted). When toEnd is true, only return a fragment if the resulting match goes to the end of the content expression.

allowsMark(markType:Β MarkType) β†’Β bool πŸ“„

Check whether a node with the given mark type is allowed after this position.

findWrapping(target:Β NodeType, targetAttrs:Β ?Object) β†’Β ?[{type:Β NodeType, attrs:Β Object}] πŸ“„

Find a set of wrapping node types that would allow a node of type target with attributes targetAttrs to appear at this position. The result may be empty (when it fits directly) and will be null when no such wrapping exists.

interface ParseSpec

A value that describes how to parse a given DOM node as a ProseMirror node or mark type. Specifies the attributes of the new node or mark, along with optional information about the way the node's content should be treated.

May either be a set of attributes, where null indicates the node's default attributes, or an array containing first a set of attributes and then an object describing the treatment of the node's content. Such an object may have the following properties:

content: ?union<bool, DOMNode>
If this is false, the content will be ignored. If it is not given, the DOM node's children will be parsed as content of the ProseMirror node or mark. If it is a DOM node, that DOM node's content is treated as the content of the new node or mark (this is useful if, for example, your DOM representation puts its child nodes in an inner wrapping node).
preserveWhiteSpace: ?bool
When given, this enables or disables preserving of whitespace when parsing the content.

interface DOMOutputSpec

A description of a DOM structure. Can be either a string, which is interpreted as a text node, a DOM node, which is interpreted as itself, or an array.

An array describes a DOM element. The first element in the array should be a string, and is the name of the DOM element. If the second element is a non-Array, non-DOM node object, it is interpreted as an object providing the DOM element's attributes. Any elements after that (including the 2nd if it's not an attribute object) are interpreted as children of the DOM elements, and must either be valid DOMOutputSpec values, or the number zero.

The number zero (pronounced β€œhole”) is used to indicate the place where a ProseMirror node's content should be inserted.

module transform

This module defines a way to transform documents. Transforming happens in Steps, which are atomic, well-defined modifications to a document. Applying a step produces a new document.

Each step provides a position map that maps positions in the old document to position in the new document. Steps can be inverted to create a step that undoes their effect, and chained together in a convenience object called a Transform.

This module does not depend on the browser API being available (i.e. you can load it into any JavaScript environment).

You can read more about transformations in this guide.

class Step πŸ“„

A step object wraps an atomic operation. It generally applies only to the document it was created for, since the positions associated with it will only make sense for that document.

New steps are defined by creating classes that extend Step, overriding the apply, invert, map, posMap and fromJSON methods, and registering your class with a unique JSON-serialization identifier using Step.jsonID.

Methods

apply(doc:Β Node) β†’Β StepResult πŸ“„

Applies this step to the given document, returning a result object that either indicates failure, if the step can not be applied to this document, or indicates success by containing a transformed document.

posMap() β†’Β PosMap πŸ“„

Get the position map that represents the changes made by this step.

invert(doc:Β Node) β†’Β Step πŸ“„

Create an inverted version of this step. Needs the document as it was before the step as input.

map(mapping:Β Mappable) β†’Β ?Step πŸ“„

Map this step through a mappable thing, returning either a version of that step with its positions adjusted, or null if the step was entirely deleted by the mapping.

toJSON() β†’Β Object πŸ“„

Create a JSON-serializeable representation of this step. By default, it'll create an object with the step's JSON id, and each of the steps's own properties, automatically calling toJSON on the property values that have such a method.

Static properties

fromJSON(schema:Β Schema, json:Β Object) β†’Β Step πŸ“„

Deserialize a step from its JSON representation. Will call through to the step class' own implementation of this method.

jsonID(id:Β string, stepClass:Β constructor<Step>) πŸ“„

To be able to serialize steps to JSON, each step needs a string ID to attach to its JSON representation. Use this method to register an ID for your step classes. Try to pick something that's unlikely to clash with steps from other modules.

class StepResult πŸ“„

The result of applying a step. Contains either a new document or a failure value.

Properties

doc: ?Node πŸ“„

The transformed document.

failed: ?string πŸ“„

Text providing information about a failed step.

Static properties

ok(doc:Β Node) β†’Β StepResult πŸ“„

Create a successful step result.

fail(message:Β string) β†’Β StepResult πŸ“„

Create a failed step result.

fromReplace(doc:Β Node, from:Β number, to:Β number, slice:Β Slice) β†’Β StepResult πŸ“„

Call Node.replace with the given arguments. Create a successful result if it succeeds, and a failed one if it throws a ReplaceError.

class AddMarkStep πŸ“„

Extends Step.

Add a mark to all inline content between two positions.

Constructor

new AddMarkStep(from:Β number, to:Β number, mark:Β Mark) πŸ“„

class RemoveMarkStep πŸ“„

Extends Step.

Remove a mark from all inline content between two positions.

Constructor

new RemoveMarkStep(from:Β number, to:Β number, mark:Β Mark) πŸ“„

class ReplaceStep πŸ“„

Extends Step.

Replace a part of the document with a slice of new content.

Constructor

new ReplaceStep(from:Β number, to:Β number, slice:Β Slice, structure:Β bool) πŸ“„

The given slice should fit the 'gap' between from and toβ€”the depths must line up, and the surrounding nodes must be able to be joined with the open sides of the slice. When structure is true, the step will fail if the content between from and to is not just a sequence of closing and then opening tokens (this is to guard against rebased replace steps overwriting something they weren't supposed to).

class ReplaceAroundStep πŸ“„

Extends Step.

Replace a part of the document with a slice of content, but preserve a range of the replaced content by moving it into the slice.

Constructor

new ReplaceAroundStep(from:Β number, to:Β number, gapFrom:Β number, gapTo:Β number, slice:Β Slice, insert:Β number, structure:Β bool) πŸ“„

Create a replace-wrap step with the given range and gap. insert should be the point in the slice into which the gap should be moved. structure has the same meaning as it has in the ReplaceStep class.

interface Mappable

There are various things that positions can be mapped through. We'll denote those as 'mappable'. This is not an actual class in the codebase, only an agreed-on interface.

map(pos:Β number, bias:Β ?number) β†’Β number πŸ“„

Map a position through this object. When given, bias (should be -1 or 1) determines in which direction to move when a chunk of content is inserted at or around the mapped position.

mapResult(pos:Β number, bias:Β ?number) β†’Β MapResult πŸ“„

Map a position, and return an object containing additional information about the mapping. The result's deleted field tells you whether the position was deleted (completely enclosed in a replaced range) during the mapping.

class MapResult πŸ“„

An object representing a mapped position with some extra information.

Properties

pos: number πŸ“„

The mapped version of the position.

deleted: bool πŸ“„

Tells you whether the position was deleted, that is, whether the step removed its surroundings from the document.

class PosMap πŸ“„

A position map, holding information about the way positions in the pre-step version of a document correspond to positions in the post-step version. This class implements Mappable.

Constructor

new PosMap(ranges:Β [number]) πŸ“„

Create a position map. The modifications to the document are represented as an array of numbers, in which each group of three represents a modified chunk as [start, oldSize, newSize].

Methods

mapResult(pos:Β number, bias:Β ?number) β†’Β MapResult πŸ“„

Map the given position through this map. The bias parameter can be used to control what happens when the transform inserted content at (or around) this positionβ€”if bias is negative, the a position before the inserted content will be returned, if it is positive, a position after the insertion is returned.

map(pos:Β number, bias:Β ?number) β†’Β number πŸ“„

Map the given position through this map, returning only the mapped position.

invert() β†’Β PosMap πŸ“„

Create an inverted version of this map. The result can be used to map positions in the post-step document to the pre-step document.

class Remapping πŸ“„

A remapping represents a pipeline of zero or more mappings. It is a specialized data structured used to manage mapping through a series of steps, typically including inverted and non-inverted versions of the same step. (This comes up when β€˜rebasing’ steps for collaboration or history management.) This class implements Mappable.

Constructor

new Remapping(head:Β ?[PosMap] = [], tail:Β ?[PosMap] = []) πŸ“„

Properties

head: [PosMap] πŸ“„

The maps in the head of the mapping are applied to input positions first, back-to-front. So the map at the end of this array (if any) is the very first one applied.

tail: [PosMap] πŸ“„

The maps in the tail are applied last, front-to-back.

Methods

addToFront(map:Β PosMap, corr:Β ?number) β†’Β number πŸ“„

Add a map to the mapping's front. If this map is the mirror image (produced by an inverted step) of another map in this mapping, that map's id (as returned by this method or addToBack) should be passed as a second parameter to register the correspondence.

addToBack(map:Β PosMap, corr:Β ?number) β†’Β number πŸ“„

Add a map to the mapping's back. If the map is the mirror image of another mapping in this object, the id of that map should be passed to register the correspondence.

mapResult(pos:Β number, bias:Β ?number) β†’Β MapResult πŸ“„

Map a position through this remapping, returning a mapping result.

map(pos:Β number, bias:Β ?number) β†’Β number πŸ“„

Map a position through this remapping.

class Transform πŸ“„

A change to a document often consists of a series of steps. This class provides a convenience abstraction to build up and track such an array of steps. A Transform object implements Mappable.

The high-level transforming methods return the Transform object itself, so that they can be chained.

Constructor

new Transform(doc:Β Node) πŸ“„

Create a transformation that starts with the given document.

Properties

doc: Node πŸ“„

The current document (the result of applying the steps in the transform).

steps: [Step] πŸ“„

The steps in this transform.

docs: [Node] πŸ“„

The documents before each of the steps.

maps: [PosMap] πŸ“„

The position maps for each of the steps in this transform.

before: Node πŸ“„

The document at the start of the transformation.

Methods

step(step:Β Step) β†’Β Transform πŸ“„

Apply a new step in this transformation, saving the result. Throws an error when the step fails.

maybeStep(step:Β Step) β†’Β StepResult πŸ“„

Try to apply a step in this transformation, ignoring it if it fails. Returns the step result.

mapResult(pos:Β number, bias:Β ?number) β†’Β MapResult πŸ“„

Map a position through the whole transformation (all the position maps in maps), and return the result.

map(pos:Β number, bias:Β ?number) β†’Β number πŸ“„

Map a position through the whole transformation, and return the mapped position.

addMark(from:Β number, to:Β number, mark:Β Mark) β†’Β Transform πŸ“„

Add the given mark to the inline content between from and to.

removeMark(from:Β number, to:Β number, mark:Β ?union<Mark, MarkType> = null) β†’Β Transform πŸ“„

Remove the given mark, or all marks of the given type, from inline nodes between from and to.

clearMarkup(from:Β number, to:Β number) β†’Β Transform πŸ“„

Remove all marks and non-text inline nodes from the given range.

delete(from:Β number, to:Β number) β†’Β Transform πŸ“„

Delete the content between the given positions.

replace(from:Β number, to:Β ?number = from, slice:Β ?Slice = Slice.empty) β†’Β Transform πŸ“„

Replace the part of the document between from and to with the part of the source between start and end.

replaceWith(from:Β number, to:Β number, content:Β union<Fragment, Node, [Node]>) β†’Β Transform πŸ“„

Replace the given range with the given content, which may be a fragment, node, or array of nodes.

insert(pos:Β number, content:Β union<Fragment, Node, [Node]>) β†’Β Transform πŸ“„

Insert the given content at the given position.

insertText(pos:Β number, text:Β string) β†’Β Transform πŸ“„

Insert the given text at pos, inheriting the marks of the existing content at that position.

insertInline(pos:Β number, node:Β Node) β†’Β Transform πŸ“„

Insert the given node at pos, inheriting the marks of the existing content at that position.

lift(range:Β NodeRange, target:Β number) β†’Β Transform πŸ“„

Split the content in the given range off from its parent, if there is subling content before or after it, and move it up the tree to the depth specified by target. You'll probably want to use liftTarget to compute target, in order to be sure the lift is valid.

wrap(range:Β NodeRange, wrappers:Β [{type:Β NodeType, attrs:Β ?Object}]) β†’Β Transform πŸ“„

Wrap the given range in the given set of wrappers. The wrappers are assumed to be valid in this position, and should probably be computed with findWrapping.

setBlockType(from:Β number, to:Β ?number = from, type:Β NodeType, attrs:Β ?Object) β†’Β Transform πŸ“„

Set the type of all textblocks (partly) between from and to to the given node type with the given attributes.

setNodeType(pos:Β number, type:Β ?NodeType, attrs:Β ?Object) β†’Β Transform πŸ“„

Change the type and attributes of the node after pos.

split(pos:Β number, depth:Β ?number = 1, typeAfter:Β ?NodeType, attrsAfter:Β ?Object) β†’Β Transform πŸ“„

Split the node at the given position, and optionally, if depth is greater than one, any number of nodes above that. By default, the part split off will inherit the node type of the original node. This can be changed by passing typeAfter and attrsAfter.

join(pos:Β number, depth:Β ?number = 1, silent:Β ?bool = false) β†’Β Transform πŸ“„

Join the blocks around the given position. When silent is true, the method will return without raising an error if the position isn't a valid place to join.

Functions

mapThrough(mappables:Β [Mappable], pos:Β number, bias:Β ?number, start:Β ?number) β†’Β number πŸ“„

Map the given position through an array of mappables. When start is given, the mapping is started at that array position.

mapThroughResult(mappables:Β [Mappable], pos:Β number, bias:Β ?number, start:Β ?number) β†’Β MapResult πŸ“„

Map the given position through an array of mappables, returning a MapResult object.

liftTarget(range:Β NodeRange) β†’Β ?number πŸ“„

Try to find a target depth to which the content in the given range can be lifted.

findWrapping(range:Β NodeRange, nodeType:Β NodeType, attrs:Β ?Object) β†’Β ?[{type:Β NodeType, attrs:Β ?Object}] πŸ“„

Try to find a valid way to wrap the content in the given range in a node of the given type. May introduce extra nodes around and inside the wrapper node, if necessary.

canSplit(doc:Β Node, pos:Β number, depth:Β ?NodeType = 1, typeAfter:Β ?Object) β†’Β bool πŸ“„

Check whether splitting at the given position is allowed.

joinable(doc:Β Node, pos:Β number) β†’Β bool πŸ“„

Test whether the blocks before and after a given position can be joined.

joinPoint(doc:Β Node, pos:Β number, dir:Β ?number = -1) β†’Β ?number πŸ“„

Find an ancestor of the given position that can be joined to the block before (or after if dir is positive). Returns the joinable point, if any.

insertPoint(doc:Β Node, pos:Β number, nodeType:Β NodeType, attrs:Β ?Object) β†’Β ?number πŸ“„

Try to find a point where a node of the given type can be inserted near pos, by searching up the node hierarchy when pos itself isn't a valid place but is at the start or end of a node. Return null if no position was found.

module schema-basic

This module defines a number of basic node and mark types, and a schema that combines them.

class Doc πŸ“„

Extends Block.

A default top-level document node type.

class BlockQuote πŸ“„

Extends Block.

A blockquote node type.

class OrderedList πŸ“„

Extends Block.

An ordered list node type. Has a single attribute, order, which determines the number at which the list starts counting, and defaults to 1.

class BulletList πŸ“„

Extends Block.

A bullet list node type.

class ListItem πŸ“„

Extends Block.

A list item node type.

class HorizontalRule πŸ“„

Extends Block.

A node type for horizontal rules.

class Heading πŸ“„

Extends Block.

A heading node type. Has a single attribute level, which indicates the heading level, and defaults to 1.

Properties

maxLevel: number πŸ“„

Controls the maximum heading level. Has the value 6 in the Heading class, but you can override it in a subclass.

class CodeBlock πŸ“„

Extends Block.

A code block / listing node type.

class Paragraph πŸ“„

Extends Block.

A paragraph node type.

class Image πŸ“„

Extends Inline.

An inline image node type. Has these attributes:

class HardBreak πŸ“„

Extends Inline.

A hard break node type.

class EmMark πŸ“„

Extends MarkType.

An emphasis mark type.

class StrongMark πŸ“„

Extends MarkType.

A strong mark type.

class LinkMark πŸ“„

Extends MarkType.

A link mark type. Has these attributes:

class CodeMark πŸ“„

Extends MarkType.

A code font mark type.

Constants

schema: Schema πŸ“„

A basic document schema.

module markdown

Defines a parser and serializer for CommonMark text (registered in the format module under "markdown").

class MarkdownParser πŸ“„

A configuration of a Markdown parser. Such a parser uses markdown-it to tokenize a file, and then runs the custom rules it is given over the tokens to create a ProseMirror document tree.

Constructor

new MarkdownParser(schema:Β Schema, tokenizer:Β MarkdownIt, tokens:Β Object) πŸ“„

Create a parser with the given configuration. You can configure the markdown-it parser to parse the dialect you want, and provide a description of the ProseMirror entities those tokens map to in the tokens object, which maps token names to descriptions of what to do with them. Such a description is an object, and may have the following properties:

node: ?string
This token maps to a single node, whose type can be looked up in the schema under the given name. Exactly one of node, block, or mark must be set.
block: ?string
This token comes in _open and _close variants (which are appended to the base token name provides a the object property), and wraps a block of content. The block should be wrapped in a node of the type named to by the property's value.
mark: ?string
This token also comes in _open and _close variants, but should add a mark (named by the value) to its content, rather than wrapping it in a node.
attrs: ?union<Object, (MarkdownToken) β†’ Object>
If the mark or node to be created needs attributes, they can be either given directly, or as a function that takes a markdown-it token and returns an attribute object.

Properties

tokens: Object πŸ“„

The value of the tokens object used to construct this parser. Can be useful to copy and modify to base other parsers on.

Methods

parse(text:Β string) β†’Β Node πŸ“„

Parse a string as CommonMark markup, and create a ProseMirror document as prescribed by this parser's rules.

class MarkdownSerializer πŸ“„

A specification for serializing a ProseMirror document as Markdown/CommonMark text.

Constructor

new MarkdownSerializer(nodes:Β Object<fn(MarkdownSerializerState, Node)>, marks:Β Object) πŸ“„

Properties

nodes: Object<fn(MarkdownSerializerState, Node)> πŸ“„

The node serializer functions for this serializer.

marks: Object πŸ“„

The mark serializer info.

Methods

serialize(content:Β Node, options:Β ?Object) β†’Β string πŸ“„

Serialize the content of the given node to CommonMark.

class MarkdownSerializerState πŸ“„

This is an object used to track state and expose methods related to markdown serialization. Instances are passed to node and mark serialization methods (see toMarkdown).

Properties

options: Object πŸ“„

The options passed to the serializer.

Methods

wrapBlock(delim:Β string, firstDelim:Β ?string, node:Β Node, f:Β fn()) πŸ“„

Render a block, prefixing each line with delim, and the first line in firstDelim. node should be the node that is closed at the end of the block, and f is a function that renders the content of the block.

ensureNewLine() πŸ“„

Ensure the current content ends with a newline.

write(content:Β ?string) πŸ“„

Prepare the state for writing output (closing closed paragraphs, adding delimiters, and so on), and then optionally add content (unescaped) to the output.

closeBlock(node:Β Node) πŸ“„

Close the block for the given node.

text(text:Β string, escape:Β ?bool) πŸ“„

Add the given text to the document. When escape is not false, it will be escaped.

render(node:Β Node) πŸ“„

Render the given node as a block.

renderContent(parent:Β Node) πŸ“„

Render the contents of parent as block nodes.

renderInline(parent:Β Node) πŸ“„

Render the contents of parent as inline content.

esc(str:Β string, startOfLine:Β ?bool) β†’Β string πŸ“„

Escape the given string so that it can safely appear in Markdown content. If startOfLine is true, also escape characters that has special meaning only at the start of the line.

repeat(str:Β string, n:Β number) β†’Β string πŸ“„

Repeat the given string n times.

Constants

defaultMarkdownParser: MarkdownParser πŸ“„

A parser parsing unextended CommonMark, without inline HTML, and producing a document in the basic schema.

defaultMarkdownSerializer: MarkdownSerializer πŸ“„

A serializer for the basic schema.

module inputrules

This module defines a plugin for attaching β€˜input rules’ to an editor, which can react to or transform text typed by the user. It also comes with a bunch of default rules that can be enabled in this plugin.

class InputRule πŸ“„

Input rules are regular expressions describing a piece of text that, when typed, causes something to happen. This might be changing two dashes into an emdash, wrapping a paragraph starting with "> " into a blockquote, or something entirely different.

Constructor

new InputRule(match:Β RegExp, filter:Β ?string, handler:Β union<string, fn(pm:Β ProseMirror, match:Β [string], pos:Β number)>) πŸ“„

Create an input rule. The rule applies when the user typed something and the text directly in front of the cursor matches match, which should probably end with $. You can optionally provide a filter, which should be a single character that always appears at the end of the match, and will be used to only apply the rule when there's an actual chance of it succeeding.

The handler can be a string, in which case the matched text will simply be replaced by that string, or a function, which will be called with the match array produced by RegExp.exec, and should produce the effect of the rule.

class InputRules πŸ“„

Manages the set of active input rules for an editor. Created with the inputRules plugin.

Methods

addRule(rule:Β InputRule) πŸ“„

Add the given input rule to the editor.

removeRule(rule:Β InputRule) β†’Β bool πŸ“„

Remove the given input rule from the editor. Returns false if the rule wasn't found.

Functions

wrappingInputRule(regexp:Β RegExp, filter:Β string, nodeType:Β NodeType, getAttrs:Β ?union<Object, fn([string]) β†’Β ?Object>, joinPredicate:Β ?fn([string], Node) β†’Β bool) β†’Β InputRule πŸ“„

Build an input rule for automatically wrapping a textblock when a given string is typed. The regexp and filter arguments are directly passed through to the InputRule constructor. You'll probably want the regexp to start with ^, so that the pattern can only occur at the start of a textblock.

nodeType is the type of node to wrap in. If it needs attributes, you can either pass them directly, or pass a function that will compute them from the regular expression match.

By default, if there's a node with the same type above the newly wrapped node, the rule will try to join those two nodes. You can pass a join predicate, which takes a regular expression match and the node before the wrapped node, and can return a boolean to indicate whether a join should happen.

textblockTypeInputRule(regexp:Β RegExp, filter:Β string, nodeType:Β NodeType, getAttrs:Β ?union<Object, fn([string]) β†’Β ?Object>) β†’Β InputRule πŸ“„

Build an input rule that changes the type of a textblock when the matched text is typed into it. You'll usually want to start your regexp with ^ to that it is only matched at the start of a textblock. The optional getAttrs parameter can be used to compute the new node's attributes, and works the same as in the wrappingInputRule function.

blockQuoteRule(nodeType:Β NodeType) β†’Β InputRule πŸ“„

Given a blockquote node type, returns an input rule that turns "> " at the start of a textblock into a blockquote.

orderedListRule(nodeType:Β NodeType) β†’Β InputRule πŸ“„

Given a list node type, returns an input rule that turns a number followed by a dot at the start of a textblock into an ordered list.

bulletListRule(nodeType:Β NodeType) β†’Β InputRule πŸ“„

Given a list node type, returns an input rule that turns a bullet (dash, plush, or asterisk) at the start of a textblock into a bullet list.

codeBlockRule(nodeType:Β NodeType) β†’Β InputRule πŸ“„

Given a code block node type, returns an input rule that turns a textblock starting with three backticks into a code block.

headingRule(nodeType:Β NodeType, maxLevel:Β number) β†’Β InputRule πŸ“„

Given a node type and a maximum level, creates an input rule that turns up to that number of # characters followed by a space at the start of a textblock into a heading whose level corresponds to the number of # signs.

Constants

inputRules: Plugin πŸ“„

A plugin for adding input rules to an editor. A common pattern of use is to call inputRules.ensure(editor).addRule(...) to get an instance of the plugin state and add a rule to it.

Takes a single option, rules, which may be an array of InputRules objects to initially add.

emDash: InputRule πŸ“„

Converts double dashes to an emdash.

ellipsis: InputRule πŸ“„

Converts three dots to an ellipsis character.

openDoubleQuote: InputRule πŸ“„

β€œSmart” opening double quotes.

closeDoubleQuote: InputRule πŸ“„

β€œSmart” closing double quotes.

openSingleQuote: InputRule πŸ“„

β€œSmart” opening single quotes.

closeSingleQuote: InputRule πŸ“„

β€œSmart” closing single quotes.

smartQuotes: [InputRule] πŸ“„

Smart-quote related input rules.

allInputRules: [InputRule] πŸ“„

All schema-independent input rules defined in this module.

This module defines a number of building blocks for ProseMirror menus, along with two menu styles, menubar and tooltipmenu.

The types defined in this module aren't the only thing you can display in your menu. Anything that conforms to this interface can be put into a menu structure.

Render the element for display in the menu. Returning null can be used to signal that this element shouldn't be displayed for the given editor state.

An icon or label that, when clicked, executes a command.

The spec used to create the menu item.

Renders the icon according to its display spec, and adds an event handler which executes the command when the representation is clicked.

The configuration object passed to the MenuItem constructor.

The function to execute when the menu item is activated.

Optional function that is used to determine whether the item is appropriate at the moment.

Determines what happens when select returns false. The default is to hide the item, you can set this to "disable" to instead render the item with a disabled style.

A predicate function to determine whether the item is 'active' (for example, the item for toggling the strong mark might be active then the cursor is in strong text).

A function that renders the item. You must provide either this, icon, or label.

Describes an icon to show for this item. The object may specify an SVG icon, in which case its path property should be an SVG path spec, and width and height should provide the viewbox in which that path exists. Alternatively, it may have a text property specifying a string of text that makes up the icon, with an optional css property giving additional CSS styling for the text. Or it may contain dom property containing a DOM node.

Makes the item show up as a text label. Mostly useful for items wrapped in a drop-down or similar menu. The object should have a label property providing the text to display.

Defines DOM title (mouseover) text for the item.

Optionally adds a CSS class to the item's DOM representation.

Optionally adds a string of inline CSS to the item's DOM representation.

Defines which event on the command's DOM representation should trigger the execution of the command. Defaults to mousedown.

A drop-down menu, displayed as a label with a downwards-pointing triangle to the right of it.

Create a dropdown wrapping the elements. Options may include the following properties:

label: string
The label to show on the drop-down control.
title: string
Sets the title attribute given to the menu control.
class: string
When given, adds an extra CSS class to the menu control.
css: string
When given, adds an extra set of CSS styles to the menu control.

Returns a node showing the collapsed menu, which expands when clicked.

Represents a submenu wrapping a group of elements that start hidden and expand to the right when hovered over or tapped.

Creates a submenu for the given group of menu elements. The following options are recognized:

label: string
The label to show on the submenu.

Renders the submenu.

renderGrouped(pm:Β ProseMirror, content:Β [union<MenuElement, [MenuElement]>]) β†’Β ?DOMFragment πŸ“„

Render the given, possibly nested, array of menu elements into a document fragment, placing separators between them (and ensuring no superfluous separators appear when some of the groups turn out to be empty).

toggleMarkItem(markType:Β MarkType, options:Β Object) β†’Β MenuItem πŸ“„

Create a menu item for toggling a mark on the selection. Will create run, active, and select properties. Other properties have to be supplied in the options object. When options.attrs is a function, it will be called with (pm: ProseMirror, callback: (attrs: ?Object)) arguments, and should produce the attributes for the mark and then call the callback. Otherwise, it may be an object providing the attributes directly.

insertItem(nodeType:Β NodeType, options:Β Object) β†’Β MenuItem πŸ“„

Create a menu item for inserting a node of the given type. Adds run and select properties to the ones provided in options. options.attrs can be an object or a function, like in toggleMarkItem.

wrapItem(nodeType:Β NodeType, options:Β Object) β†’Β MenuItem πŸ“„

Build a menu item for wrapping the selection in a given node type. Adds run and select properties to the ones present in options. options.attrs may be an object or a function, as in toggleMarkItem.

blockTypeItem(nodeType:Β NodeType, options:Β Object) β†’Β MenuItem πŸ“„

Build a menu item for changing the type of the textblock around the selection to the given type. Provides run, active, and select properties. Others must be given in options. options.attrs may be an object to provide the attributes for the textblock node.

wrapListItem(nodeType:Β NodeType, options:Β Object) β†’Β MenuItem πŸ“„

Build a menu item for wrapping the selection in a list. options.attrs may be an object to provide the attributes for the list node.

icons: Object πŸ“„

A set of basic editor-related icons. Contains the properties join, lift, selectParentNode, undo, redo, strong, em, code, link, bulletList, orderedList, and blockquote, each holding an object that can be used as the icon option to MenuItem.

joinUpItem: MenuItem πŸ“„

Menu item for the joinUp command.

liftItem: MenuItem πŸ“„

Menu item for the lift command.

selectParentNodeItem: MenuItem πŸ“„

Menu item for the selectParentNode command.

undoItem: MenuItem πŸ“„

Menu item for the undo command.

redoItem: MenuItem πŸ“„

Menu item for the redo command.

Plugin that enables the menu bar for an editor. The menu bar takes up space above the editor, showing currently available commands (that have been added to the menu). The following options are supported:

float: bool = false
When enabled, causes the menu bar to stay visible when the editor is partially scrolled out of view, by making it float at the top of the viewport.
content: [MenuGroup]
Determines the content of the menu.
tooltipMenu: Plugin πŸ“„

Enables the tooltip menu for this editor. This menu shows up when there is a selection, and optionally in certain other circumstances, providing context-relevant commands.

By default, the tooltip will show inline menu commands (registered with the menuGroup command property) when there is an inline selection, and block related commands when there is a node selection on a block.

The plugin supports the following options:

showLinks: bool = true
Causes a tooltip with the link target to show up when the cursor is inside of a link (without a selection).
selectedBlockMenu: bool = false
When enabled, and a whole block is selected or the cursor is inside an empty block, the block menu gets shown.
inlineContent: [MenuGroup]
The menu elements to show when displaying the menu for inline content.
blockContent: [MenuGroup]
The menu elements to show when displaying the menu for block content.
selectedBlockContent: [MenuGroup]
The elements to show when a full block has been selected and selectedBlockMenu is enabled. Defaults to concatenating inlineContent and blockContent.
position: string
Where, relative to the selection, the tooltip should appear. Defaults to "above". Can also be set to "below".

module ui

This module implements some GUI primitives.

The prompting implementation gets the job done, roughly, but it's rather primitive and you'll probably want to replace it in your own system (or submit patches to improve this implementation).

class Tooltip πŸ“„

Used to show tooltips. An instance of this class is a persistent DOM node (to allow position and opacity animation) that can be shown and hidden. It is positioned relative to a position (passed when showing the tooltip), and points at that position with a little arrow-like triangle attached to the node.

Constructor

new Tooltip(wrapper:Β DOMNode, options:Β union<string, Object>) πŸ“„

Create a new tooltip that lives in the wrapper node, which should be its offset anchor, i.e. it should have a relative or absolute CSS position. You'll often want to pass an editor's wrapper node. options may be an object containg a direction string and a getBoundingRect function which should return a rectangle determining the space in which the tooltip may appear. Alternatively, options may be a string specifying the direction. The direction can be "above", "below", "right", "left", or "center". In the latter case, the tooltip has no arrow and is positioned centered in its wrapper node.

Methods

detach() πŸ“„

Remove the tooltip from the DOM.

open(node:Β DOMNode, pos:Β ?{left:Β number, top:Β number}) πŸ“„

Make the tooltip visible, show the given node in it, and position it relative to the given position. If pos is not given, the tooltip stays in its previous place. Unless the tooltip's direction is "center", pos should definitely be given the first time it is shown.

close() πŸ“„

Close (hide) the tooltip.

class FieldPrompt πŸ“„

This class represents a dialog that prompts for a set of fields.

Constructor

new FieldPrompt(pm:Β ProseMirror, title:Β string, fields:Β [Field]) πŸ“„

Construct a prompt. Note that this does not open it yet.

Properties

form: DOMNode πŸ“„

An HTML form wrapping the fields.

Methods

close() πŸ“„

Close the prompt.

open() πŸ“„

Open the prompt's dialog.

values() β†’Β ?[any] πŸ“„

Read the values from the form's field. Validate them, and when one isn't valid (either has a validate function that produced an error message, or has no validate function, no value, and no default value), show the problem to the user and return null.

prompt() β†’Β {close:Β fn()} πŸ“„

Open a prompt with the parameter form in it. The default implementation calls openPrompt.

reportInvalid(dom:Β DOMNode, message:Β string) πŸ“„

Report a field as invalid, showing the given message to the user.

class Field πŸ“„

The type of field that FieldPrompt expects to be passed to it.

Constructor

new Field(options:Β Object) πŸ“„

Create a field with the given options. Options support by all field types are:

value: ?any
The starting value for the field.
label: string
The label for the field.
required: ?bool
Whether the field is required.
validate: ?(any) β†’ ?string
A function to validate the given value. Should return an error message if it is not valid.

Methods

render(pm:Β ProseMirror) β†’Β DOMNode πŸ“„

Render the field to the DOM. Should be implemented by all subclasses.

read(dom:Β DOMNode) β†’Β any πŸ“„

Read the field's value from its DOM node.

validateType(_value:Β any) β†’Β ?string πŸ“„

A field-type-specific validation function.

class TextField πŸ“„

Extends Field.

A field class for single-line text fields.

class SelectField πŸ“„

Extends Field.

A field class for dropdown fields based on a plain <select> tag. Expects an option options, which should be an array of {value: string, label: string} objects, or a function taking a ProseMirror instance and returning such an array.

Functions

openPrompt(pm:Β ProseMirror, content:Β DOMNode, options:Β ?Object) β†’Β {close:Β fn()} πŸ“„

Open a dialog box for the given editor, putting content inside of it. The close method on the return value can be used to explicitly close the dialog again. The following options are supported:

pos: {left: number, top: number}
Provide an explicit position for the element. By default, it'll be placed in the center of the editor.
onClose: fn()
A function to be called when the dialog is closed.

module collab

This module implements an API into which a communication channel for collaborative editing can be hooked. See this guide for more details and an example.

class Collab πŸ“„

This class accumulates changes that have to be sent to the central authority in the collaborating group, signals an event when it has something to send, and makes it possible to integrate changes made by peers into our local document. It is created and attached to the editor when the plugin is enabled, and can be accessed with collabEditing.get.

Properties

version: number πŸ“„

The version number of the last update received from the central authority. Starts at 0 or the value of the version property in the option object, for the editor's value when the option was enabled.

mustSend: Subscription<fn()> πŸ“„

Fired when there are new steps to send to the central authority. Consumers should respond by calling sendableSteps and pushing those to the authority.

receivedTransform: Subscription<fn(transform:Β Transform, selectionBeforeTransform:Β Selection)> πŸ“„

Signals that a transformation has been aplied to the editor. Passes the Transform and the selection before the transform as arguments to the handler.

Methods

hasSendableSteps() β†’Β bool πŸ“„

Reports whether the editor has any unsent steps.

sendableSteps() β†’Β {version:Β number, steps:Β [Step]} πŸ“„

Provides the data describing the editor's unconfirmed steps. The version and array of steps are the things you'd send to the central authority. The whole return value must be passed to confirmSteps when the steps go through.

receive(steps:Β [Step], clientIDs:Β [number]) β†’Β [PosMap] πŸ“„

Pushes a set of steps (received from the central authority) into the editor. Will recognize its own changes, and confirm unconfirmed steps as appropriate. Remaining unconfirmed steps will be rebased over remote steps.

Returns the position maps produced by applying the steps.

Constants

collabEditing: Plugin πŸ“„

Enables the collaborative editing framework for the editor.

You can pass a version option, which determines the starting version number of the collaborative editing, and defaults to 0.

module example-setup

This module exports helper functions for deriving a set of basic menu items, input rules, or key bindings from a schema. These values need to know about the schema for two reasonsβ€”they need access to specific instances of node and mark types, and they need to know which of the node and mark types that they know about are actually present in the schema.

The exampleSetup plugin ties these together into a plugin that will automatically enable this basic functionality in an editor.

Functions

buildInputRules(schema:Β Schema) β†’Β [InputRule] πŸ“„

A set of input rules for creating the basic block quotes, lists, code blocks, and heading.

buildKeymap(schema:Β Schema, mapKeys:Β ?Object) β†’Β Keymap πŸ“„

Inspect the given schema looking for marks and nodes from the basic schema, and if found, add key bindings related to them. This will add:

  • Mod-B for toggling strong
  • Mod-I for toggling emphasis
  • Mod-` for toggling code font
  • Ctrl-Shift-0 for making the current textblock a paragraph
  • Ctrl-Shift-1 to Ctrl-Shift-6 for making the current textblock a heading of the corresponding level
  • Ctrl-Shift-\ to make the current textblock a code block
  • Ctrl-Shift-8 to wrap the selection in an ordered list
  • Ctrl-Shift-9 to wrap the selection in a bullet list
  • Ctrl-Shift-. to wrap the selection in a block quote
  • Enter to split a non-empty textblock in a list item while at the same time splitting the list item
  • Mod-Enter to insert a hard break
  • Mod-Shift-minus to insert a horizontal rule

You can suppress or map these bindings by passing a mapKeys argument, which maps key names (say "Mod-B" to either false, to remove the binding, or a new key name string.

buildMenuItems(schema:Β Schema) β†’Β Object πŸ“„

Given a schema, look for default mark and node types in it and return an object with relevant menu items relating to those marks:

toggleStrong: MenuItem
A menu item to toggle the strong mark.
toggleEm: MenuItem
A menu item to toggle the emphasis mark.
toggleCode: MenuItem
A menu item to toggle the code font mark.
toggleLink: MenuItem
A menu item to toggle the link mark.
insertImage: MenuItem
A menu item to insert an image.
wrapBulletList: MenuItem
A menu item to wrap the selection in a bullet list.
wrapOrderedList: MenuItem
A menu item to wrap the selection in an ordered list.
wrapBlockQuote: MenuItem
A menu item to wrap the selection in a block quote.
makeParagraph: MenuItem
A menu item to set the current textblock to be a normal paragraph.
makeCodeBlock: MenuItem
A menu item to set the current textblock to be a code block.
makeHead[N]: MenuItem
Where N is 1 to 6. Menu items to set the current textblock to be a heading of level N.
insertHorizontalRule: MenuItem
A menu item to insert a horizontal rule.

The return value also contains some prefabricated menu elements and menus, that you can use instead of composing your own menu from scratch:

insertMenu: Dropdown
A dropdown containing the insertImage and insertHorizontalRule items.
typeMenu: Dropdown
A dropdown containing the items for making the current textblock a paragraph, code block, or heading.
inlineMenu: [[MenuElement]]
An array of arrays of menu elements for use as the inline menu to, for example, a tooltip menu.
blockMenu: [[MenuElement]]
An array of arrays of menu elements for use as the block menu to, for example, a tooltip menu.
fullMenu: [[MenuElement]]
An array of arrays of menu elements for use as the full menu for, for example the menu bar.

Constants

exports

module util/orderedmap

class OrderedMap πŸ“„

Persistent data structure representing an ordered mapping from strings to values, with some convenient update methods.

Properties

size: number πŸ“„

The amount of keys in this map.

Methods

get(key:Β string) β†’Β ?any πŸ“„

Retrieve the value stored under key, or return undefined when no such key exists.

update(key:Β string, value:Β any, newKey:Β ?string) β†’Β OrderedMap πŸ“„

Create a new map by replacing the value of key with a new value, or adding a binding to the end of the map. If newKey is given, the key of the binding will be replaced with that key.

remove(key:Β string) β†’Β OrderedMap πŸ“„

Return a map with the given key removed, if it existed.

addToStart(key:Β string, value:Β any) β†’Β OrderedMap πŸ“„

Add a new key to the start of the map.

addToEnd(key:Β string, value:Β any) β†’Β OrderedMap πŸ“„

Add a new key to the end of the map.

addBefore(place:Β string, key:Β string, value:Β any) β†’Β OrderedMap πŸ“„

Add a key after the given key. If place is not found, the new key is added to the end.

forEach(f:Β fn(key:Β string, value:Β any)) πŸ“„

Call the given function for each key/value pair in the map, in order.

prepend(map:Β union<Object, OrderedMap>) β†’Β OrderedMap πŸ“„

Create a new map by prepending the keys in this map that don't appear in map before the keys in map.

append(map:Β union<Object, OrderedMap>) β†’Β OrderedMap πŸ“„

Create a new map by appending the keys in this map that don't appear in map after the keys in map.

subtract(map:Β union<Object, OrderedMap>) β†’Β OrderedMap πŸ“„

Create a map containing all the keys in this map that don't appear in map.

Static properties

from(value:Β ?union<Object, OrderedMap>) β†’Β OrderedMap πŸ“„

Return a map with the given content. If null, create an empty map. If given an ordered map, return that map itself. If given an object, create a map from the object's properties.