Editor Transforms

API reference for editor transformation operations in Slate.

Transforms are helper functions that manipulate a Slate document.

Node Operations

duplicateNodes

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

OptionsDuplicateNodesOptions

Collapse all

    insertNodes options.

    Location to duplicate from and insert after. Defaults to selection.

    If true, duplicates blocks above location. Ignored if nodes provided.

    Specific nodes to duplicate. Takes precedence over block.

insertFragment

Insert a fragment of nodes at a location.

Parameters

Collapse all

    Fragment of nodes to insert.

OptionsInsertFragmentOptions

Collapse all

    Location to insert at. Defaults to selection.

    Whether range is hanging.

    Allow insertion in void nodes.

insertNode

Insert a single node atomically.

Parameters

Collapse all

    Node to insert.

insertNodes

Insert one or more nodes atomically.

Parameters

Collapse all

    Node(s) to insert.

OptionsInsertNodesOptions

Collapse all

    Common query options.

    Insert after the current block if removeEmpty caused it to be removed.

    Remove the current block if empty. Defaults to removing an empty paragraph, but can be customized.

    Select inserted nodes.

    Allow insertion in void nodes.

liftNodes

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

OptionsLiftNodesOptions

Collapse all

mergeNodes

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

OptionsMergeNodesOptions

Collapse all

    Custom function to handle node merging.

    Custom function to remove empty ancestor after merging.

moveNodes

Move the nodes from an origin to a destination.

OptionsMoveNodesOptions

Collapse all

    Destination path.

    Move only children of the node at the location.

    Start index of the children to move. Default is 0.

removeNodes

Remove nodes at a location.

OptionsRemoveNodesOptions

Collapse all

    When true, remove all children of the node at the specified location.

    Remove the previous empty block if it exists.

replaceNodes

Replace nodes at a location with new nodes.

Parameters

Collapse all

    The new node(s) to insert.

OptionsReplaceNodesOptions

Collapse all

    insertNodes options.

    Replace all children of the node at the specified location instead of the node itself.

    Options for removing nodes before the replacement.

reset

Reset the editor state including history, selection and children.

OptionsResetOptions

Collapse all

    replaceNodes options.

    When true, only reset the children without clearing history/operations.

setNodes

Set properties on nodes.

Parameters

Collapse all

    Properties to set. Use undefined to unset.

OptionsSetNodesOptions

Collapse all

    When true, only apply to text nodes in non-void or markable void nodes.

splitNodes

Split nodes at a location.

OptionsSplitNodesOptions

Collapse all

toggleBlock

Toggle the block type at a location.

Parameters

Collapse all

    The block type to toggle.

OptionsToggleBlockOptions

Collapse all

    Options to pass to setNodes.

    The default block type when untoggling. Defaults to paragraph.

    Options for determining if the block is active.

    If true, toggles wrapping with type. Otherwise, sets the block type directly.

unsetNodes

Remove properties from nodes.

Parameters

Collapse all

    Property key(s) to remove.

OptionsUnsetNodesOptions

Collapse all

unwrapNodes

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

OptionsUnwrapNodesOptions

Collapse all

wrapNodes

Wrap nodes at a location in the element container.

Parameters

Collapse all

    The wrapper element.

OptionsWrapNodesOptions

Collapse all

    When true, wrap all children into a single container element.

Text Operations

delete

Delete text at a location.

OptionsDeleteTextOptions

Collapse all

    Number of characters (or other unit) to delete. Default is 1.

    If true, delete backward.

    Unit to delete by.

deleteBackward

Delete text backward.

Parameters

Collapse all

    Defaults to 'character'.

deleteForward

Delete text forward.

Parameters

Collapse all

    Defaults to 'character'.

deleteFragment

Delete a fragment of nodes.

OptionsEditorFragmentDeletionOptions

Collapse all

    Direction to delete.

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

Parameters

Collapse all

    Text to insert.

OptionsInsertTextOptions

Collapse all

    Location to insert text at. Takes precedence over current selection.

    Whether to allow insertion in void nodes.

    • Default: true When true and editor has marks, the inserted text will include those marks. When false, inserts plain text without marks.

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.

Optionsobject

Collapse all

    How many units to move. Defaults to 1.

    Defaults to 'character'.

    Move backward if true.

    Which edge to move.

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.

Parameters

Collapse all

    Mark key to add.

    Value for the mark.

addMarks

Add multiple marks to the current selection.

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

Parameters

Collapse all

    Key-value pairs of mark props.

OptionsAddMarksOptions

Collapse all

    Mark keys to remove first. For mutually exclusive marks, e.g. subscript/superscript.

removeMark

Remove a mark from text in the selection.

Parameters

Collapse all

    Mark key to remove.

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
editor.tf.removeMarks()             // remove all marks
editor.tf.removeMarks('bold')       // remove the 'bold' mark
editor.tf.removeMarks(['bold','italic'])
editor.tf.removeMarks('bold', { at: range })

Parameters

Collapse all

    Mark key(s) to remove. If not provided and selection is collapsed, clears all marks from editor.marks.

OptionsRemoveMarksOptions

Collapse all

    Custom range to remove marks from. Takes precedence over current selection.

    • Default: true Whether to trigger onChange when modifying editor.marks.

    Whether to split nodes when removing marks.

    Custom function to filter which nodes to remove marks from.

    Whether to allow removing marks from void nodes.

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
editor.tf.toggleMark('bold')                                // Toggle bold on/off
editor.tf.toggleMark('subscript', { remove: 'superscript'}) // Remove superscript before adding subscript

Parameters

Collapse all

    The mark key to toggle.

OptionsToggleMarkOptions

Collapse all

    Mark key(s) to remove before adding the mark. Useful for mutually exclusive marks like subscript/superscript. The specified mark key is always removed in addition to these marks.

Selection

collapse

Collapse the selection to a point.

Optionsobject

Collapse all

    Edge to collapse to. Defaults to 'anchor'.

deselect

Unset the current selection.

move

Move the selection's point.

Optionsobject

Collapse all

    Defaults to 1.

    Defaults to 'character'.

    If true, move backward.

    Which edge to move.

select

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

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

Parameters

Collapse all

    Location to select.

OptionsSelectOptions

Collapse all

    Select the start or end edge above at.

    Focus the editor before selecting.

    Select the start of the next sibling.

    Select the end of the previous sibling.

setPoint

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

Parameters

Collapse all

    Point properties to update.

Optionsobject

Collapse all

    Which edge of the selection to set.

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.

Parameters

Collapse all

    A partial range to update existing selection properties.

DOM Operations

blur

Blur the editor.

deselectDOM

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

focus

Focus the editor.

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

OptionsFocusOptions

Collapse all

    Select this location before focusing.

    Focus at the edge of the location or the editor.

    Number of attempts to refocus.

insertData

Insert data from a DataTransfer into the editor. Calls:

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

Parameters

Collapse all

    Data to insert from clipboard or drag event.

insertFragmentData

Insert fragment data from a DataTransfer into the editor.

Parameters

Collapse all

    Data to parse as fragment.

insertTextData

Insert text data from a DataTransfer into the editor.

Parameters

Collapse all

    Text data to insert.

setFragmentData

Sets data from the currently selected fragment on a DataTransfer.

Parameters

Collapse all

    DataTransfer to store the fragment.

History Operations

redo

Redo to the next saved state.

undo

Undo to the previous saved state.

setSplittingOnce

Parameters

Collapse all

    Whether the next operation should split into a new batch in history.

withMerging

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

Parameters

Collapse all

    Batched changes to merge into the previous history point.

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.

Parameters

Collapse all

    Batched changes in a new history point.

withoutMerging

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

Parameters

Collapse all

    Changes not merged into any existing history point.

withoutSaving

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

Parameters

Collapse all

    Changes not saved into history at all.

Core Operations

apply

Apply an operation in the editor.

Parameters

Collapse all

    Operation to apply.

normalizeNode

Normalize a node according to the editor's schema.

Parameters

Collapse all

    The node entry to normalize.

Options{ operation?: Operation }

Collapse all

    The triggering operation.

normalize

Normalize dirty nodes in the editor.

OptionsEditorNormalizeOptions

Collapse all

    When true, forcibly re-normalize all nodes.

withoutNormalizing

Call a function, deferring normalization until after it completes.

Parameters

Collapse all

    A synchronous function to execute without normalization in between operations.

Returnsboolean

    True if normalization was performed afterwards.