Transforms API

On this page

• Node options
• Node methods
• Block methods
• Break methods
• Fragment methods
• Slice methods
• Text methods
• Selection methods
• Mark methods
• Value and root methods
• State field methods
• Correction methods
• Effect methods
• Canonical change methods

Node options

Node methods accept method-specific options objects. These options appear across most node methods:

• at?: NodeTarget: An explicit location or live descendant to change. When omitted inside editor.update(...), selection-sensitive methods use the transaction target.
• type?: NodeTypeSelector: Select one structural type or any type in an array.
• match?: NodeMatch<Node>: A predicate that adds computed conditions. The selected type determines the predicate's node type.
• mode?: 'highest' | 'lowest': Controls which matching node level is used. Methods documented with mode?: 'highest' | 'lowest' | 'all' also accept all.
• voids?: boolean: Includes void elements when true.

Node methods

Use node methods from tx.nodes.

tx.nodes.insert(nodes: Descendant | readonly Descendant[], options?)

Insert nodes at options.at or the transaction target.

Options: at, mode, hanging, select, split, voids.

• hanging?: boolean: Preserve hanging range edges.
• select?: boolean: Select the inserted nodes.
• split?: { type?, match? }: Select which ancestor to split before insertion.

tx.nodes.remove(options?)

Remove nodes at options.at or the transaction target.

Options: at, type, match, mode, hanging, voids.

tx.nodes.merge(options?)

Merge a node with the previous node at the same depth.

Options: at, type, match, mode, hanging, voids.

tx.nodes.split(options?)

Split nodes at a location.

Options: at, type, match, mode, always, height, position, voids.

• always?: boolean: Split even when the target is already at an edge.
• height?: number: Split at an ancestor height.
• position?: number: Split at an explicit child position.

tx.nodes.wrap(element: Element, options?)

Wrap matching nodes in element.

Options: at, type, match, mode, split, voids.

tx.nodes.unwrap(options?)

Unwrap matching nodes.

Options: at, type, match, mode, split, voids.

tx.nodes.set(props, options?)

Set properties on matching nodes.

Options: at, type, match, mode, hanging, split, voids, compare, merge.

• compare?: PropsCompare: Decide whether a property should be written.
• merge?: PropsMerge: Merge incoming and existing property values.

Pass an exact node as at to preserve its property inference.

Set one or several properties in the same patch. Their values are inferred from the editor's closed Value type:

Use undefined to remove a property in the same atomic patch:

For an aliased persisted property, use its exact schema key as a computed object key. Prefix handles cannot address one property.

tx.nodes.unset(props, options?)

Unset properties on matching nodes.

Options: at, type, match, mode, hanging, split, voids.

tx.nodes.lift(options?)

Lift matching nodes upward in the document tree.

Options: at, type, match, mode, voids.

tx.nodes.move(options)

Move nodes from options.at to options.to.

Options: at, type, match, mode, to, voids.

• to: Path: Destination path for the moved nodes.

Block methods

Use semantic block mutations from tx.blocks inside a transaction or from editor.update.blocks for a direct update.

tx.blocks.insert(blocks, options?)

Insert one or more block elements after a block, before a block or at a path, and return the keys of the top-level blocks that landed, in order. Without a placement, the blocks land after the selection's block: a range uses its document-order end and a node selection its final selected block. An absent selection appends to the current root.

Act on what landed through the returned keys, not the nodes you passed. A key resolves its block from any root for as long as the block exists. When the editor's length limit cuts the batch, the result leaves out each block it dropped, and each non-empty block it admits lands as a copy under its own key. Any other block that is live in another root lands under its source's key, so its returned key can resolve to that source.

The insert checks the parent the blocks land in. When they do not fit, because that parent already holds as many children as it allows or does not allow their type, nothing changes and the method returns undefined. It also returns undefined when an after or before target does not resolve. An at path past its parent's last child throws. The update keeps its other changes after a refusal, so check the result before you act on the inserted blocks.

The options take one of after, before and at, and replaceEmpty only with after or no placement. The type refuses other combinations, and passing one throws.

Options:

• after?: NodeSelectionTarget: Insert after this block, given as a location, live descendant, node key or node selection.
• before?: NodeTarget: Insert before this block.
• at?: Path: Insert at this path, a slot among its parent's children.
• select?: boolean: Select the inserted blocks.
• replaceEmpty?: boolean: Replace the empty editable, non-atomic text block the blocks land after, in the same transaction. Applies only to an after or selection landing. Nonempty sources and empty structural or atomic blocks remain intact.

tx.blocks.duplicate(options?)

Duplicate the targeted blocks after the last matching block.

tx.blocks.reset(options?)

Reset each targeted block to the default element declared by its immediate parent, or by its document root for a top-level block. The mutation preserves the block's children, selection, and live node key. Element properties survive only when their schema lifecycle uses typeChange: "preserve-if-allowed" and the destination element accepts them. A surviving property keeps its value, and its generator does not run. A block already of the default type also keeps the values its schema has no default or generator for.

Reset checks every target before it writes. It returns false and changes nothing when one target has no default it can become:

• its parent or root declares no element default, or declares text;
• the default needs a required property that neither the schema nor the block supplies;
• changing the block to the default's type leaves its content without a required property;
• the default is not allowed at the target's position, such as a heading the parent requires first.

Otherwise it returns true. Any other failure to build a default throws. The update does not roll back on false, so check the result before composing other edits.

Options:

• at: A document location, live node or key, or exact node selection. Defaults to the active text or exact node selection.
• unset: Property names or a schema property handle to remove when the default does not set them, such as a level a block keeps when it is already its parent's default.

tx.blocks.set(props, options?)

Set properties on the targeted schema blocks. When at is omitted, the active selection is the target. Use tx.nodes.set when the target is not specifically a block.

tx.blocks.toggle(props, options?)

Toggle targeted blocks between the complete props shape and their immediate parent or document-root default block shape. Turning blocks off resets them as tx.blocks.reset does, so it returns false and changes nothing when one target has no default it can become.

Pass { wrap: true } to wrap or unwrap the targeted blocks instead.

Break methods

Use break methods from tx.break.

tx.break.insert()

Insert a block break at the transaction target.

tx.break.insertSoft()

Insert a soft break at the transaction target.

Fragment methods

Use fragment methods from tx.fragment.

tx.fragment(options?)

Read the fragment at options.at or the current selection.

Options:

• at?: Range: Range to read. Defaults to the active selection.
• unwrap?: readonly string[]: Omit matching wrapper element types from the returned fragment.

tx.fragment.delete(options?)

Delete the fragment at options.at or the transaction target.

Options:

• at?: NodeTarget: Location or live descendant to delete. Defaults to the transaction target.
• direction?: 'forward' | 'backward': Direction used for collapsed deletion.

tx.fragment.replace(content, options?)

Fit and replace known-closed content at options.at or the transaction target. The method returns false without mutating when the target cannot be resolved, is a protected void, or the content cannot fit the compiled schema.

Options:

• at?: NodeTarget: Replacement range, point, path, or live descendant.
• hanging?: boolean: Preserve hanging range edges instead of un-hanging first.
• voids?: boolean: Allow replacement inside void elements.

Slice methods

Use tx.slice for parsed or imported content whose open edges must be fitted against the compiled schema at its actual replacement range.

tx.slice.replace(slice: ContentSlice, options?)

Fit and atomically replace content at options.at or the transaction target. The slice's optional roots map carries detached transitive secondary roots; insertion remaps copied keys deterministically and preserves shared aliases. The method returns false without mutating when the target cannot be resolved, is a protected void, or a well-formed slice cannot fit. Malformed slice shapes are programmer errors and throw. The method returns true once a fitted replacement is accepted, including a valid replacement whose canonical change is empty.

Options:

• at?: NodeTarget: Replacement range, point, path, or live descendant.
• hanging?: boolean: Preserve hanging range edges instead of un-hanging first.
• voids?: boolean: Allow replacement inside void elements.

Text methods

tx.text.insert(text: string, options?)

Insert text at options.at or the transaction target.

Options:

• at?: NodeTarget: Where to insert. Defaults to the transaction target.
• voids?: boolean: Allow insertion into void elements.

When at is an expanded range, the inserted text replaces the range and the selection moves after the inserted text.

tx.text.delete(options?)

Delete text at options.at or the transaction target.

Options:

• at?: NodeTarget: Location or live descendant to delete from. Defaults to the transaction target.
• distance?: number: Number of units to delete. Defaults to one unit.
• unit?: 'character' | 'word' | 'line' | 'block': Unit used for collapsed deletion.
• reverse?: boolean: Delete before the target instead of after it.
• hanging?: boolean: Preserve hanging range edges instead of un-hanging first.
• voids?: boolean: Allow deletion inside void elements.

tx.text.deleteBackward(options?)

Delete before the transaction target.

Options:

• unit?: 'character' | 'word' | 'line' | 'block': Unit to delete. Defaults to one character.

tx.text.deleteForward(options?)

Delete after the transaction target.

Options:

• unit?: 'character' | 'word' | 'line' | 'block': Unit to delete. Defaults to one character.

Selection methods

tx.selection reads the transaction selection and exposes the same query predicates as editor.read.selection: contains(target), intersects(target), isCollapsed(), isExpanded(), isWithinBlock(options?), isAcrossBlocks(options?), isAtBlockStart(options?), and isAtBlockEnd(options?).

tx.selection.set(target: EditorSelection | Location | null)

Set the selection to a new target.

tx.selection.setNodes(targets: readonly (Path | NodeKey | Descendant)[])

Select live nodes in the transaction draft. The transaction resolves every target in one root and canonicalizes exact membership. An empty collection clears the selection.

tx.selection.set(null)

Clear the selection.

tx.selection.collapse(options?)

Collapse the selection to a single point.

Options:

• edge?: 'anchor' | 'focus' | 'start' | 'end': Edge to collapse to.

tx.selection.move(options?)

Move the selection by offset, character, word, or line.

Options:

• distance?: number: Number of units to move.
• unit?: 'offset' | 'character' | 'word' | 'line': Unit used for movement.
• reverse?: boolean: Move backward.
• edge?: 'anchor' | 'focus' | 'start' | 'end': Selection edge to move.

tx.selection.setPoint(props: Partial<Point>, options?)

Set properties on one selection point.

Options:

• edge?: 'anchor' | 'focus' | 'start' | 'end': Selection edge to update.

Mark methods

tx.marks()

Return the active marks for the transaction.

tx.marks.add(key: string, value: unknown)

Add a mark to the current selection or pending marks.

tx.marks.remove(key: string)

Remove a mark from the current selection or pending marks.

tx.marks.set(marks: Record<string, unknown> | null)

Replace the pending insertion marks. Use {} to force plain inserted text at a collapsed selection, or null to let inserted text inherit from the selected text position.

tx.marks.toggle(key: string, value?)

Toggle a mark for the current selection or pending marks. Mutual exclusion belongs to the text-property declarations in the editor schema.

Value and root methods

Use value and root methods for whole-root or whole-document replacement. Normal typing commands should use tx.text, tx.nodes, tx.fragment, or tx.selection.

For one-shot snapshot imports, call the direct update method:

selection accepts a complete text or node selection, null, "start", or "end". Use SelectionApi.text(range) to import a plain range. Snapshot imports reset local history. Configure tags through editor.update(policy).

tx.value.replace(input: SnapshotInput)

Replace the complete serializable document inside a larger transaction.

The input is complete: omitted named roots are deleted and omitted persisted meta fields reset to their declared initial values. Omitted selection is cleared. The schema fits the imported content; a fitting failure throws and discards the update. The method returns void. Use tx.roots for a partial named-root change and tx.setField for one metadata field.

tx.roots.create(root: NamedRootKey, children: Value)

Create a named root.

tx.roots.replace(root: NamedRootKey, children: Value)

Replace an existing named root.

tx.roots.delete(root: NamedRootKey)

Delete an extra root. The primary document is not deleted through tx.roots.

State field methods

tx.setField(field, value)

Write a registered state field.

State-field writes emit the field's typed effect and list the field key in commit.dirtyStateKeys.

Effect methods

tx.effects.emit(type, value)

Emit a typed effect. Installed state fields reduce effects during the same transaction. Effect descriptors define history inversion, collaboration policy, and mapping through canonical document changes.

Correction methods

editor.update.value.repair()

Repair every document root with the installed corrections. This maintenance method starts a history-skipped update, cannot run inside another update, and publishes no commit when the value is already canonical. Ordinary grouped updates run deterministic corrections over ranges changed by the transaction.

Canonical change methods

tx.changes.apply(change: DocumentChange)

Apply one root-aware canonical document change to the active draft. This is the adapter and history boundary for serialized or remote changes; ordinary editing uses semantic transaction groups.