Unveiling ProseMirror: Architecture, State, View, and Transform Explained

Background

ProseMirror is a popular rich‑text editor. Its official site provides many examples and demos.

Rich‑text editors render HTML/CSS but must provide a way to edit the underlying structure. Browsers offer contenteditable and document.execCommand, but using them directly is problematic.

Typical architecture is shown below.

Code Structure

ProseMirror consists of four core modules: prosemirror-model: defines the document model. prosemirror-state: describes overall editor state. prosemirror-view: UI component that renders the state. prosemirror-transform: provides transaction methods for modifying the document.

The article focuses on the state, view, and transform modules.

Typical Flow

Initialization Flow

Initialization creates a schema, then an editor state, and finally an editor view.

// create schema
const demoSchema = new Schema({
  nodes: addListNodes(schema.spec.nodes, "paragraph block*", "block"),
  marks: schema.spec.marks
})

// create state
let state = EditorState.create({
  doc: DOMParser.fromSchema(demoSchema).parse(document.querySelector("#content")),
  plugins: exampleSetup({ schema: demoSchema })
})

// create view
let view = EditorView(document.querySelector('.full'), { state })

The state holds doc, selection, storedMarks, and scrollToSelection. The doc contains the document structure parsed from the initial HTML.

Because the editor is data‑driven ( F(state)=view), keeping state and view consistent is crucial.

Update Flow

When a user types a character, the view changes, which triggers a state update, preserving consistency. Custom elements are handled by updating the state then calling updateState on the view.

ProseMirror builds a transaction (a subclass of transform) containing one or more step objects such as AddMarkStep, RemoveMarkStep, ReplaceStep, and ReplaceAroundStep. Each step implements apply and invert for execution and undo.

State Layer

The state is extensible and includes four core properties: doc, selection, storedMarks, and scrollToSelection. The doc is a tree of nodes, each containing fragments of child nodes. ProseMirror stores formatting marks (e.g., strong, em) as mark objects attached to text nodes, resulting in a stable inline representation.

Using offsets to describe positions matches user expectations and improves performance over tree manipulation.

Stable ordering of marks ensures a unique document representation.

View Layer

The view renders the state to editable DOM elements. When the view updates, it calls each node’s toDOM method to create DOM elements, and uses parseDOM to serialize DOM back into document data.

Every initialization or state change triggers updateState, which refreshes the UI.

Transform Layer

Changes in the view generate a transaction (a transform) that updates the state. For example, inserting text creates an insertText transaction containing a ReplaceStep. Built‑in steps such as AddMarkStep, RemoveMarkStep, ReplaceStep, and ReplaceAroundStep provide the core editing operations.

References

ProseMirror GitHub: https://github.com/prosemirror

Official site: https://prosemirror.net/