prosekit/pm/state

AllSelection

Extends Selection

A selection type that represents selecting the whole document (which can not necessarily be expressed with a text selection, when there are for example leaf block nodes at the start or end of the document).

constructor

new AllSelection(doc: ProseMirrorNode): AllSelection

eq

Test whether the selection is the same as another selection.

const eq: (other: Selection) => boolean

getBookmark

Get a bookmark for this selection, which is a value that can be mapped without having access to a current document, and later resolved to a real selection for a given document again. (This is used mostly by the history to track and restore old selections.) The default implementation of this method just converts the selection to a text selection and returns the bookmark for that.

const getBookmark: () => { map: any; resolve: any }

map

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

const map: (doc: ProseMirrorNode) => AllSelection

replace

Replace the selection with a slice or, if no slice is given, delete the selection. Will append to the given transaction.

const replace: (tr: Transaction, content?: Slice) => void

toJSON

Convert the selection to a JSON representation. When implementing this for a custom selection class, make sure to give the object a type property whose value matches the ID under which you registered your class.

const toJSON: () => any

EditorState

The state of a ProseMirror editor is represented by an object of this type. A state is a persistent data structure—it isn’t updated, but rather a new state value is computed from an old one using the apply method.

A state holds a number of built-in fields, and plugins can define additional fields.

constructor

new EditorState(): EditorState

doc: ProseMirrorNode

The current document.

selection: Selection

The selection.

storedMarks: null | readonly Mark[]

A set of marks to apply to the next input. Will be null when no explicit marks have been set.

get plugins(): readonly ProseMirrorPlugin<any>[]

The plugins that are active in this state.

get schema(): Schema

The schema of the state’s document.

get tr(): Transaction

Start a transaction from this state.

apply

Apply the given transaction to produce a new state.

const apply: (tr: Transaction) => EditorState

applyTransaction

Verbose variant of apply that returns the precise transactions that were applied (which might be influenced by the transaction hooks of plugins) along with the new state.

const applyTransaction: (rootTr: Transaction) => { state: EditorState; transactions: readonly Transaction[] }

reconfigure

Create a new state based on this one, but with an adjusted set of active plugins. State fields that exist in both sets of plugins are kept unchanged. Those that no longer exist are dropped, and those that are new are initialized using their init method, passing in the new configuration object..

const reconfigure: (config: { plugins?: readonly ProseMirrorPlugin<any>[] }) => EditorState

toJSON

Serialize this state to JSON. If you want to serialize the state of plugins, pass an object mapping property names to use in the resulting JSON object to plugin objects. The argument may also be a string or number, in which case it is ignored, to support the way JSON.stringify calls toString methods.

const toJSON: (pluginFields?: { [propName]: ProseMirrorPlugin<any> }) => any

create

Create a new state.

const create: (config: EditorStateConfig) => EditorState

fromJSON

Deserialize a JSON representation of a state. config should have at least a schema field, and should contain array of plugins to initialize the state with. pluginFields can be used to deserialize the state of plugins, by associating plugin instances with the property names they use in the JSON object.

const fromJSON: (config: { plugins?: readonly ProseMirrorPlugin<any>[]; schema: Schema }, json: any, pluginFields?: { [propName]: ProseMirrorPlugin<any> }) => EditorState

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 a selection, from and to point directly before and after the selected node, anchor equals from, and head equals to..

constructor

new NodeSelection($pos: ResolvedPos): NodeSelection

node: ProseMirrorNode

The selected node.

content

Get the content of this selection as a slice.

const content: () => Slice

eq

Test whether the selection is the same as another selection.

const eq: (other: Selection) => boolean

getBookmark

const getBookmark: () => NodeBookmark

map

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

const map: (doc: ProseMirrorNode, mapping: Mappable) => Selection

toJSON

const toJSON: () => any

create

Create a node selection from non-resolved positions.

const create: (doc: ProseMirrorNode, from: number) => NodeSelection

isSelectable

Determines whether the given node may be selected as a node selection.

const isSelectable: (node: ProseMirrorNode) => boolean

PluginKey

A key is used to tag plugins in a way that makes it possible to find them, given an editor state. Assigning a key does mean only one plugin of that type can be active in a state.

constructor

new PluginKey<PluginState>(name?: string): PluginKey<PluginState>

get

Get the active plugin with this key, if any, from an editor state.

const get: (state: EditorState) => undefined | ProseMirrorPlugin<PluginState>

getState

Get the plugin’s state from an editor state.

const getState: (state: EditorState) => undefined | PluginState

ProseMirrorPlugin

Plugins bundle functionality that can be added to an editor. They are part of the editor state and may influence that state and the view that contains it.

constructor

new ProseMirrorPlugin<PluginState>(spec: PluginSpec<PluginState>): ProseMirrorPlugin<PluginState>

props: EditorProps<ProseMirrorPlugin<PluginState>>

The props exported by this plugin.

spec: PluginSpec<PluginState>

The plugin’s spec object.

getState

Extract the plugin’s state field from an editor state.

const getState: (state: EditorState) => undefined | PluginState

Selection

Superclass for editor selections. Every selection type should extend this. Should not be instantiated directly.

constructor

new Selection($anchor: ResolvedPos, $head: ResolvedPos, ranges?: readonly SelectionRange[]): Selection

$anchor: ResolvedPos

The resolved anchor of the selection (the side that stays in place when the selection is modified).

$head: ResolvedPos

The resolved head of the selection (the side that moves when the selection is modified).

ranges: readonly SelectionRange[]

The ranges covered by the selection.

visible: boolean

Controls whether, when a selection of this type is active in the browser, the selected range should be visible to the user. Defaults to true.

get $from(): ResolvedPos

The resolved lower bound of the selection’s main range.

get $to(): ResolvedPos

The resolved upper bound of the selection’s main range.

get anchor(): number

The selection’s anchor, as an unresolved position.

get empty(): boolean

Indicates whether the selection contains any content.

get from(): number

The lower bound of the selection’s main range.

get head(): number

The selection’s head.

get to(): number

The upper bound of the selection’s main range.

content

Get the content of this selection as a slice.

const content: () => Slice

eq

Test whether the selection is the same as another selection.

const eq: (selection: Selection) => boolean

getBookmark

const getBookmark: () => SelectionBookmark

map

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

const map: (doc: ProseMirrorNode, mapping: Mappable) => Selection

replace

Replace the selection with a slice or, if no slice is given, delete the selection. Will append to the given transaction.

const replace: (tr: Transaction, content?: Slice) => void

replaceWith

Replace the selection with the given node, appending the changes to the given transaction.

const replaceWith: (tr: Transaction, node: ProseMirrorNode) => void

toJSON

const toJSON: () => any

atEnd

Find the cursor or leaf node selection closest to the end of the given document.

const atEnd: (doc: ProseMirrorNode) => Selection

atStart

Find the cursor or leaf node selection closest to the start of the given document. Will return an AllSelection if no valid position exists.

const atStart: (doc: ProseMirrorNode) => Selection

findFrom

Find a valid cursor or leaf node selection starting at the given position and searching back if dir is negative, and forward if positive. When textOnly is true, only consider cursor selections. Will return null when no valid selection position is found.

const findFrom: ($pos: ResolvedPos, dir: number, textOnly?: boolean) => null | Selection

fromJSON

Deserialize the JSON representation of a selection. Must be implemented for custom classes (as a static class method).

const fromJSON: (doc: ProseMirrorNode, json: any) => Selection

jsonID

To be able to deserialize selections from JSON, custom selection classes must register themselves with an ID string, so that they can be disambiguated. Try to pick something that’s unlikely to clash with classes from other modules.

const jsonID: (id: string, selectionClass: { fromJSON: (doc: ProseMirrorNode, json: any) => Selection }) => { fromJSON: (doc: ProseMirrorNode, json: any) => Selection }

near

Find a valid cursor or leaf node selection near the given position. Searches forward first by default, but if bias is negative, it will search backwards first.

const near: ($pos: ResolvedPos, bias?: number) => Selection

SelectionRange

Represents a selected range in a document.

constructor

new SelectionRange($from: ResolvedPos, $to: ResolvedPos): SelectionRange

$from: ResolvedPos

The lower bound of the range.

$to: ResolvedPos

The upper bound of the range.

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): TextSelection

get $cursor(): null | ResolvedPos

Returns a resolved position if this is a cursor selection (an empty text selection), and null otherwise.

eq

Test whether the selection is the same as another selection.

const eq: (other: Selection) => boolean

getBookmark

const getBookmark: () => TextBookmark

map

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

const map: (doc: ProseMirrorNode, mapping: Mappable) => Selection

replace

Replace the selection with a slice or, if no slice is given, delete the selection. Will append to the given transaction.

const replace: (tr: Transaction, content?: Slice) => void

toJSON

const toJSON: () => any

between

Return a text selection that spans the given positions or, if they aren’t text positions, find a text selection near them. bias determines whether the method searches forward (default) or backwards (negative number) first. Will fall back to calling Selection.near when the document doesn’t contain a valid text position.

const between: ($anchor: ResolvedPos, $head: ResolvedPos, bias?: number) => Selection

create

Create a text selection from non-resolved positions.

const create: (doc: ProseMirrorNode, anchor: number, head?: number) => TextSelection

Transaction

Extends Transform

An editor state transaction, which can be applied to a state to create an updated state. Use EditorState.tr to create an instance.

Transactions track changes to the document (they are a subclass of Transform), but also other state changes, like selection updates and adjustments of the set of stored marks. In addition, you can store metadata properties in a transaction, which are extra pieces of information that client code or plugins can use to describe what a transaction represents, so that they can update their own state accordingly.

The editor view uses a few metadata properties: it will attach a property "pointer" with the value true to selection transactions directly caused by mouse or touch input, a "composition" property holding an ID identifying the composition that caused it to transactions caused by composed DOM input, and a "uiEvent" property of that may be "paste", "cut", or "drop".

storedMarks: null | readonly Mark[]

The stored marks set by this transaction, if any.

time: number

The timestamp associated with this transaction, in the same format as Date.now().

get isGeneric(): boolean

Returns true if this transaction doesn’t contain any metadata, and can thus safely be extended.

get scrolledIntoView(): boolean

True when this transaction has had scrollIntoView called on it.

get selection(): Selection

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

get selectionSet(): boolean

Whether the selection was explicitly updated by this transaction.

get storedMarksSet(): boolean

Whether the stored marks were explicitly set for this transaction.

addStoredMark

Add a mark to the set of stored marks.

const addStoredMark: (mark: Mark) => this

deleteSelection

Delete the selection.

const deleteSelection: () => this

ensureMarks

Make sure the current stored marks or, if that is null, the marks at the selection, match the given set of marks. Does nothing if this is already the case.

const ensureMarks: (marks: readonly Mark[]) => this

getMeta

Retrieve a metadata property for a given name or plugin.

const getMeta: (key: string | ProseMirrorPlugin<any> | PluginKey<any>) => any

insertText

Replace the given range, or the selection if no range is given, with a text node containing the given string.

const insertText: (text: string, from?: number, to?: number) => this

removeStoredMark

Remove a mark or mark type from the set of stored marks.

const removeStoredMark: (mark: MarkType | Mark) => this

replaceSelection

Replace the current selection with the given slice.

const replaceSelection: (slice: Slice) => this

replaceSelectionWith

Replace the selection with the given node. When inheritMarks is true and the content is inline, it inherits the marks from the place where it is inserted.

const replaceSelectionWith: (node: ProseMirrorNode, inheritMarks?: boolean) => this

scrollIntoView

Indicate that the editor should scroll the selection into view when updated to the state produced by this transaction.

const scrollIntoView: () => this

setMeta

Store a metadata property in this transaction, keyed either by name or by plugin.

const setMeta: (key: string | ProseMirrorPlugin<any> | PluginKey<any>, value: any) => this

setSelection

Update the transaction’s current selection. Will determine the selection that the editor gets when the transaction is applied.

const setSelection: (selection: Selection) => this

setStoredMarks

Set the current stored marks.

const setStoredMarks: (marks: null | readonly Mark[]) => this

setTime

Update the timestamp for the transaction.

const setTime: (time: number) => this

EditorStateConfig

The type of object passed to EditorState.create.

doc?: ProseMirrorNode: The starting document. Either this or schema must be provided.
plugins?: readonly ProseMirrorPlugin<any>[]: The plugins that should be active in this state.
schema?: Schema<any, any>: The schema to use (only relevant if no doc is specified).
selection?: Selection: A valid selection in the document.
storedMarks?: null | readonly Mark[]: The initial set of stored marks.

PluginSpec

This is the type passed to the Plugin constructor. It provides a definition for a plugin.

appendTransaction?: (transactions: readonly Transaction[], oldState: EditorState, newState: EditorState) => undefined | null | Transaction: Allows the plugin to append another transaction to be applied after the given array of transactions. When another plugin appends a transaction after this was called, it is called again with the new state and new transactions—but only the new transactions, i.e. it won’t be passed transactions that it already saw.
filterTransaction?: (tr: Transaction, state: EditorState) => boolean: When present, this will be called before a transaction is applied by the state, allowing the plugin to cancel it (by returning false).
key?: PluginKey<any>: Can be used to make this a keyed plugin. You can have only one plugin with a given key in a given state, but it is possible to access the plugin’s configuration and state through the key, without having access to the plugin instance object.
props?: EditorProps<ProseMirrorPlugin<PluginState>>: The view props added by this plugin. Props that are functions will be bound to have the plugin instance as their this binding.
state?: StateField<PluginState>: Allows a plugin to define a state field, an extra slot in the state object in which it can keep its own data.
view?: (view: EditorView) => PluginView: When the plugin needs to interact with the editor view, or set something up in the DOM, use this field. The function will be called when the plugin’s state is associated with an editor view.

SelectionBookmark

A lightweight, document-independent representation of a selection. You can define a custom bookmark type for a custom selection class to make the history handle it well.

map: (mapping: Mappable) => SelectionBookmark: Map the bookmark through a set of changes.
resolve: (doc: ProseMirrorNode) => Selection: Resolve the bookmark to a real selection again. This may need to do some error checking and may fall back to a default (usually TextSelection.between) if mapping made the bookmark invalid.

StateField

A plugin spec may provide a state field (under its state property) of this type, which describes the state it wants to keep. Functions provided here are always called with the plugin instance as their this binding.

apply: (tr: Transaction, value: T, oldState: EditorState, newState: EditorState) => T: Apply the given transaction to this state field, producing a new field value. Note that the newState argument is again a partially constructed state does not yet contain the state from plugins coming after this one.
fromJSON?: (config: EditorStateConfig, value: any, state: EditorState) => T: Deserialize the JSON representation of this field. Note that the state argument is again a half-initialized state.
init: (config: EditorStateConfig, instance: EditorState) => T: Initialize the value of the field. config will be the object passed to EditorState.create. Note that instance is a half-initialized state instance, and will not have values for plugin fields initialized after this one.
toJSON?: (value: T) => any: Convert this field to JSON. Optional, can be left off to disable JSON serialization for the field.

Command

Commands are functions that take a state and a an optional transaction dispatch function and…

determine whether they apply to this state
if not, return false
if dispatch was passed, perform their effect, possibly by passing a transaction to dispatch
return true

In some cases, the editor view is passed as a third argument.

Type: (state: EditorState, dispatch?: (tr: Transaction) => void, view?: EditorView) => boolean

PluginView

A stateful object that can be installed in an editor by a plugin.

Type: { destroy?: () => void; update?: (view: EditorView, prevState: EditorState) => void }