Editor Transforms

Transforms are helper functions that manipulate a Plate document.

Node Operations

duplicateNodes

Duplicates nodes at a location and inserts them after that location.

insertFragment

Insert a fragment of nodes at a location.

insertNode

Insert a single node atomically.

insertNodes

Insert one or more nodes atomically.

liftNodes

Lift nodes at the specified location upwards in the document tree. If necessary, the parent node is split.

mergeNodes

Merge a node at the specified location with the previous node at the same depth. Resulting empty container nodes are removed.

moveNodes

Move the nodes from an origin to a destination.

removeNodes

Remove nodes at a location.

replaceNodes

Replace nodes at a location with new nodes.

reset

Reset the editor state including history, selection and children.

setNodes

Set properties on nodes.

splitNodes

Split nodes at a location.

toggleBlock

Toggle the block type at a location.

unsetNodes

Remove properties from nodes.

unwrapNodes

Unwrap a node at a location. If necessary, the parent node is split.

wrapNodes

Wrap nodes at a location in the element container.

Text Operations

delete

Delete text at a location.

deleteBackward

Delete text backward.

deleteForward

Delete text forward.

deleteFragment

Delete a fragment of nodes.

insertText

Insert text at a location, optionally with marks. The behavior depends on the provided options:

1. If at is specified in options, inserts at that location regardless of selection
2. Otherwise, if there's a selection:
   • If marks is true (default) and editor has marks, inserts text with those marks
   • If no marks, inserts plain text
3. If neither at nor selection exists, no text is inserted

insertBreak

Insert a block break at the current selection.

insertSoftBreak

Insert a soft break at the current selection. A soft break is a new line in the current block.

deselect

Unset the selection.

move

Move the selection's point forward or backward.

Mark Operations

addMark

Add a custom property to the leaf text nodes within non-void nodes or void nodes that editor.markableVoid() allows in the current selection. If the selection is currently collapsed, the marks will be added to the editor.marks property instead, and applied when text is inserted next.

addMarks

Add multiple marks to the current selection.

Copyeditor.tf.addMarks({ bold: true, italic: true })
editor.tf.addMarks({ bold: subscript }, { remove: 'superscript' })
editor.tf.addMarks({ bold: true }, { remove: ['italic', 'underline'] })

removeMark

Remove a mark from text in the selection.

removeMarks

Remove marks from text nodes in the current selection or from editor.marks. The behavior depends on the selection state and options:

1. If selection is expanded or is in a markable void node:
   • Remove specified mark keys from text nodes
2. If selection is collapsed and no custom range provided:
   • Remove specified keys from editor.marks
   • If no keys specified, clear all marks from editor.marks
3. If custom range provided (at option):
   • Only remove marks from text nodes in that range

Copyeditor.tf.removeMarks()             // remove all marks
editor.tf.removeMarks('bold')       // remove the 'bold' mark
editor.tf.removeMarks(['bold','italic'])
editor.tf.removeMarks('bold', { at: range })

toggleMark

Toggle a mark on or off in the current selection. If the mark exists, removes it. If it doesn't exist:

1. Removes any specified marks in the remove option
2. Adds the mark with value true

Copyeditor.tf.toggleMark('bold')                                // Toggle bold on/off
editor.tf.toggleMark('subscript', { remove: 'superscript'}) // Remove superscript before adding subscript

Selection

collapse

Collapse the selection to a point.

deselect

Unset the current selection.

move

Move the selection's point.

select

Set the selection to a new value specified by at. When a selection already exists, this method just calls setSelection.

Copyeditor.tf.select(at)
editor.tf.select(at, { edge: 'end' })
editor.tf.select(at, { edge: 'start' })

setPoint

Set new properties on one of the selection's points.

setSelection

Set new properties on an active selection. Since the value is a Partial<Range>, this method can only handle updates to an existing selection. If there is no active selection the operation will be void. Use select if you'd like to create a selection when there is none.

DOM Operations

blur

Blur the editor.

deselectDOM

Deselect the editor's DOM selection in addition to deselect.

focus

Focus the editor.

Copyeditor.tf.focus()
editor.tf.focus({ edge: 'end' })
editor.tf.focus({ edge: 'endEditor' })

insertData

Insert data from a DataTransfer into the editor. Calls:

1. insertFragmentData(editor: ReactEditor, data: DataTransfer)
2. insertTextData(editor: ReactEditor, data: DataTransfer)

insertFragmentData

Insert fragment data from a DataTransfer into the editor.

insertTextData

Insert text data from a DataTransfer into the editor.

setFragmentData

Sets data from the currently selected fragment on a DataTransfer.

History Operations

redo

Redo to the next saved state.

undo

Undo to the previous saved state.

setSplittingOnce

withMerging

Apply a series of changes inside a synchronous fn, These operations will be merged into the previous history.

withNewBatch

Apply a series of changes inside a synchronous fn, ensuring that the first operation starts a new batch in the history. Subsequent operations will be merged as usual.

withoutMerging

Apply a series of changes inside a synchronous fn, without merging any of the new operations into previous save point in the history.

withoutSaving

Apply a series of changes inside a synchronous fn, without saving any of their operations into the history.

Core Operations

apply

Apply an operation in the editor.

normalizeNode

Normalize a node according to the editor's schema.

normalize

Normalize dirty nodes in the editor.

withoutNormalizing

Call a function, deferring normalization until after it completes.

Keyboard Shortcuts

moveLine

Handle ArrowUp and ArrowDown keyboard events.

Default behavior: Returns false (allows Plate's default line movement).

Usage:

Copyconst plugin = createPlatePlugin({
  key: 'myPlugin',
}).overrideEditor(() => ({
  transforms: {
    moveLine: ({ reverse }) => {
      // Custom line movement logic
      if (reverse) {
        // Handle ArrowUp
      } else {
        // Handle ArrowDown  
      }
      return true; // Prevent default
    },
  },
}));

tab

Handle Tab and Shift+Tab keyboard events.

Default behavior: Returns false (allows default browser tab navigation).

Usage:

Copyconst plugin = createPlatePlugin({
  key: 'myPlugin',
}).overrideEditor(() => ({
  transforms: {
    tab: ({ reverse }) => {
      if (reverse) {
        // Handle Shift+Tab (usually outdent)
        editor.tf.outdent();
      } else {
        // Handle Tab (usually indent)
        editor.tf.indent();
      }
      return true; // Prevent default
    },
  },
}));

selectAll

Handle Cmd+A / Ctrl+A keyboard events.

Default behavior: Returns false (allows default browser select all).

Usage:

Copyconst plugin = createPlatePlugin({
  key: 'myPlugin',
}).overrideEditor(() => ({
  transforms: {
    selectAll: () => {
      // Custom select all logic
      const blockEntry = editor.api.block();
      if (blockEntry) {
        editor.tf.select(blockEntry[1]);
        return true; // Prevent default
      }
      return false; // Allow default
    },
  },
}));

escape

Handle Escape keyboard events.

Default behavior: Returns false (allows default browser escape handling).

Usage:

Copyconst plugin = createPlatePlugin({
  key: 'myPlugin',
}).overrideEditor(() => ({
  transforms: {
    escape: () => {
      // Custom escape logic (e.g., exit special mode)
      if (editor.api.inSpecialMode()) {
        editor.tf.exitSpecialMode();
        return true; // Prevent default
      }
      return false; // Allow default
    },
  },
}));