slate/docs/reference/models/transform.md

Transform

import { Transform } from 'slate'

A transform allows you to define a series of changes you'd like to make to the current Document or Selection in a State.

All changes are performed through Transform objects, so that a history of changes can be preserved for use in undo/redo operations, and to make collaborative editing possible.

Transform methods can either operate on the Document, the Selection, or both at once.

• Properties
  • state
• Methods
  • apply
  • call
• Current State Transforms
  • deleteBackward
  • deleteForward
  • delete
  • insertBlock
  • insertFragment
  • insertInline
  • insertText
  • addMark
  • setBlock
  • setInline
  • splitBlock
  • splitInline
  • removeMark
  • toggleMark
  • unwrapBlock
  • unwrapInline
  • wrapBlock
  • wrapInline
  • wrapText
• Selection Transforms
  • blur
  • collapseTo{Edge}Of
  • collapseTo{Edge}Of{Direction}Block
  • collapseTo{Edge}Of{Direction}Text
  • collapseTo{Edge}
  • extendTo{Edge}Of
  • extend{Direction}
  • focus
  • moveToOffsets
  • moveToRangeOf
  • moveTo
  • move{Direction}
• Node Transforms
  • addMarkByKey
  • insertNodeByKey
  • insertTextByKey
  • moveNodeByKey
  • removeMarkByKey
  • removeNodeByKey
  • removeTextByKey
  • setMarkByKey
  • setNodeByKey
  • splitNodeByKey
  • unwrapInlineByKey
  • unwrapBlockByKey
  • unwrapNodeByKey
  • wrapBlockByKey
  • wrapInlineByKey
• Document Transforms
  • deleteAtRange
  • deleteBackwardAtRange
  • deleteForwardAtRange
  • insertBlockAtRange
  • insertFragmentAtRange
  • insertInlineAtRange
  • insertTextAtRange
  • addMarkAtRange
  • setBlockAtRange
  • setInlineAtRange
  • splitBlockAtRange
  • splitInlineAtRange
  • removeMarkAtRange
  • toggleMarkAtRange
  • unwrapBlockAtRange
  • unwrapInlineAtRange
  • wrapBlockAtRange
  • wrapInlineAtRange
  • wrapTextAtRange
• History Transforms
  • redo
  • undo

Properties

state

A State with the transform's current operations applied. Each time you run a new transform function this property will be updated.

Methods

apply

apply(options: Object) => State

Applies all of the current transform steps, returning the newly transformed State. An options object is optional, containing values of:

• save: Boolean — override the editor's built-in logic of whether to create a new snapshot in the history, that can be reverted to later.

call

call(customTransform: Function, ...arguments) => Transform

This method calls the provided function argument customTransform with the current instance of the Transform object as the first argument and passes through the remaining arguments.

The function signature for customTransform is:

customTransform(transform: Transform, ...arguments)

The purpose of call is to enable custom transform methods to exist and called in a chain. For example:

return state.transform()
  .call(myCustomInsertTableTransform, columns, rows)
  .focus()
  .apply()

Current State Transforms

deleteBackward

deleteBackward(n: Number) => Transform

Delete backward n characters at the current cursor. If the selection is expanded, this method is equivalent to a regular delete(). n defaults to 1.

deleteForward

deleteForward(n: Number) => Transform

Delete forward n characters at the current cursor. If the selection is expanded, this method is equivalent to a regular delete(). n defaults to 1.

delete

delete() => Transform

Delete everything in the current selection.

insertBlock

insertBlock(block: Block) => Transform
insertBlock(properties: Object) => Transform
insertBlock(type: String) => Transform

Insert a new block at the same level as the current block, splitting the current block to make room if it is non-empty. If the selection is expanded, it will be deleted first.

insertFragment

insertFragment(fragment: Document) => Transform

Insert a fragment at the current selection. If the selection is expanded, it will be deleted first.

insertInline

insertInline(inline: Inline) => Transform
insertInline(properties: Object) => Transform

Insert a new inline at the current cursor position, splitting the text to make room if it is non-empty. If the selection is expanded, it will be deleted first.

insertText

insertText(text: String) => Transform

Insert a string of text at the current selection. If the selection is expanded, it will be deleted first.

addMark

addMark(mark: Mark) => Transform
addMark(properties: Object) => Transform
addMark(type: String) => Transform

Add a mark to the characters in the current selection. For convenience, you can pass a type string or properties object to implicitly create a Mark of that type.

setBlock

setBlock(properties: Object) => Transform
setBlock(type: String) => Transform

Set the properties of the Block in the current selection. For convenience, you can pass a type string to set the blocks's type only.

setInline

setInline(properties: Object) => Transform
setInline(type: String) => Transform

Set the properties of the Inline nodes in the current selection. For convenience, you can pass a type string to set the inline's type only.

splitBlock

splitBlock(depth: Number) => Transform

Split the Block in the current selection by depth levels. If the selection is expanded, it will be deleted first. depth defaults to 1.

splitInline

splitInline(depth: Number) => Transform

Split the Inline node in the current selection by depth levels. If the selection is expanded, it will be deleted first. depth defaults to Infinity.

removeMark

removeMark(mark: Mark) => Transform
removeMark(properties: Object) => Transform
removeMark(type: String) => Transform

Remove a mark from the characters in the current selection. For convenience, you can pass a type string or properties object to implicitly create a Mark of that type.

toggleMark

toggleMark(mark: Mark) => Transform
toggleMark(properties: Object) => Transform
toggleMark(type: String) => Transform

Add or remove a mark from the characters in the current selection, depending on it already exists on any or not. For convenience, you can pass a type string or properties object to implicitly create a Mark of that type.

unwrapBlock

unwrapBlock([type: String], [data: Data]) => Transform

Unwrap all Block nodes in the current selection that match a type and/or data.

unwrapInline

unwrapInline([type: String], [data: Data]) => Transform

Unwrap all Inline nodes in the current selection that match a type and/or data.

wrapBlock

wrapBlock(type: String, [data: Data]) => Transform

Wrap the Block nodes in the current selection with a new Block node of type, with optional data.

wrapInline

wrapInline(type: String, [data: Data]) => Transform

Wrap the Inline nodes in the current selection with a new Inline node of type, with optional data.

wrapText

wrapText(prefix: String, [suffix: String]) => Transform

Surround the text in the current selection with prefix and suffix strings. If the suffix is ommitted, the prefix will be used instead.

Selection Transforms

blur

blur() => Transform

Blur the current selection.

collapseTo{Edge}

collapseTo{Edge}() => Transform

Collapse the current selection to its {Edge}. Where {Edge} is either Anchor, Focus, Start or End.

collapseTo{Edge}Of

collapseTo{Edge}Of(node: Node) => Transform

Collapse the current selection to the {Edge} of node. Where {Edge} is either Start or End.

collapseTo{Edge}Of{Direction}Block

collapseTo{Edge}Of{Direction}Block() => Transform

Collapse the current selection to the {Edge} of the next Block node in {Direction}. Where {Edge} is either {Start} or {End} and {Direction} is either Next or Previous.

collapseTo{Edge}Of{Direction}Text

collapseTo{Edge}Of{Direction}Text() => Transform

Collapse the current selection to the {Edge} of the next Text node in {Direction}. Where {Edge} is either {Start} or {End} and {Direction} is either Next or Previous.

extend{Direction}

extend{Direction}(n: Number) => Transform

Extend the current selection's points n characters in {Direction}. Where {Direction} is either Backward or Forward.

extendTo{Edge}Of

extendTo{Edge}Of(node: Node) => Transform

Extend the current selection to the {Edge} of a node. Where {Edge} is either Start or End.

focus

focus() => Transform

Focus the current selection.

move{Direction}

move{Direction}(n: Number) => Transform

Move the current selection's points n characters in {Direction}. Where {Direction} is either Backward or Forward.

moveToOffsets

moveToOffsets(anchorOffset: Number, focusOffset: Number) => Transform

Move the current selection's offsets to a new anchorOffset and focusOffset.

moveToRangeOf

moveToRangeOf(node: Node) => Transform

Move the current selection's anchor point to the start of a node and its focus point to the end of the node.

moveTo

moveTo(properties: Selection || Object) => Transform

Move the current selection to a selection with merged properties. The properties can either be a Selection object or a plain Javascript object of selection properties.

Node Transforms

addMarkByKey

addMarkByKey(key: String, offset: Number, length: Number, mark: Mark) => Transform

Add a mark to length characters starting at an offset in a Node by its key.

insertNodeByKey

insertNodeByKey(key: String, index: Number, node: Node) => Transform

Insert a node at index inside a parent Node by its key.

insertTextByKey

insertTextByKey(key: String, offset: Number, text: String, [marks: Set]) => Transform

Insert text at an offset in a Node with optional marks.

moveNodeByKey

moveNodeByKey(key: String, newKey: String, newIndex: Number) => Transform

Move a Node by its key to a new parent node with its newKey and at a newIndex.

removeMarkByKey

removeMarkByKey(key: String, offset: Number, length: Number, mark: Mark) => Transform

Remove a mark from length characters starting at an offset in a Node by its key.

removeNodeByKey

removeNodeByKey(key: String) => Transform

Remove a Node from the document by its key.

removeTextByKey

removeTextByKey(key: String, offset: Number, length: Number) => Transform

Remove length characters of text starting at an offset in a Node by its key.

setMarkByKey

setMarkByKey(key: String, offset: Number, length: Number, mark: Mark, properties: Object) => Transform

Set a dictionary of properties on a mark on a Node by its key.

setNodeByKey

setNodeByKey(key: String, properties: Object) => Transform
setNodeByKey(key: String, type: String) => Transform

Set a dictionary of properties on a Node by its key. For convenience, you can pass a type string or properties object.

splitNodeByKey

splitNodeByKey(key: String, offset: Number) => Transform

Split a node by its key at an offset.

unwrapInlineByKey

unwrapInlineByKey(key: String, properties: Object) => Transform
unwrapInlineByKey(key: String, type: String) => Transform

Unwrap all inner content of an Inline node that match properties. For convenience, you can pass a type string or properties object.

unwrapBlockByKey

unwrapBlockByKey(key: String, properties: Object) => Transform
unwrapBlockByKey(key: String, type: String) => Transform

Unwrap all inner content of a Block node that match properties. For convenience, you can pass a type string or properties object.

unwrapNodeByKey

unwrapNodeByKey(key: String) => Transform

Unwrap a single node from its parent. If the node is surrounded with siblings, its parent will be split. If the node is the only child, the parent is removed, and simply replaced by the node itself. Cannot unwrap a root node.

wrapBlockByKey

wrapBlockByKey(key: String, properties: Object) => Transform
wrapBlockByKey(key: String, type: String) => Transform

Wrap the given node in a Block node that match properties. For convenience, you can pass a type string or properties object.

wrapInlineByKey

wrapInlineByKey(key: String, properties: Object) => Transform
wrapInlineByKey(key: String, type: String) => Transform

Wrap the given node in a Inline node that match properties. For convenience, you can pass a type string or properties object.

Document Transforms

deleteBackwardAtRange

deleteBackwardAtRange(range: Selection, n: Number) => Transform

Delete backward n characters at a range. If the range is expanded, this method is equivalent to a regular delete(). n defaults to 1.

deleteForwardAtRange

deleteForwardAtRange(range: Selection, n: Number) => Transform

Delete forward n characters at a range. If the range is expanded, this method is equivalent to a regular delete(). n defaults to 1.

deleteAtRange

deleteAtRange(range: Selection, ) => Transform

Delete everything in a range.

insertBlockAtRange

insertBlockAtRange(range: Selection, block: Block) => Transform
insertBlockAtRange(range: Selection, properties: Object) => Transform
insertBlockAtRange(range: Selection, type: String) => Transform

Insert a new block at the same level as the leaf block at a range, splitting the current block to make room if it is non-empty. If the selection is expanded, it will be deleted first.

insertFragmentAtRange

insertFragmentAtRange(range: Selection, fragment: Document) => Transform

Insert a fragment at a range. If the selection is expanded, it will be deleted first.

insertInlineAtRange

insertInlineAtRange(range: Selection, inline: Inline) => Transform
insertInlineAtRange(range: Selection, properties: Object) => Transform

Insert a new inline at a range, splitting the text to make room if it is non-empty. If the selection is expanded, it will be deleted first.

insertTextAtRange

insertTextAtRange(range: Selection, text: String) => Transform

Insert a string of text at a range. If the selection is expanded, it will be deleted first.

addMarkAtRange

addMarkAtRange(range: Selection, mark: Mark) => Transform
addMarkAtRange(range: Selection, properties: Object) => Transform
addMarkAtRange(range: Selection, type: String) => Transform

Add a mark to the characters in a range. For convenience, you can pass a type string or properties object to implicitly create a Mark of that type.

setBlockAtRange

setBlockAtRange(range: Selection, properties: Object) => Transform
setBlock(range: Selection, type: String) => Transform

Set the properties of the Block in a range. For convenience, you can pass a type string to set the blocks's type only.

setInlineAtRange

setInlineAtRange(range: Selection, properties: Object) => Transform
setInline(range: Selection, type: String) => Transform

Set the properties of the Inline nodes in a range. For convenience, you can pass a type string to set the inline's type only.

splitBlockAtRange

splitBlockAtRange(range: Selection, depth: Number) => Transform

Split the Block in a range by depth levels. If the selection is expanded, it will be deleted first. depth defaults to 1.

splitInlineAtRange

splitInlineAtRange(range: Selection, depth: Number) => Transform

Split the Inline node in a range by depth levels. If the selection is expanded, it will be deleted first. depth defaults to Infinity.

removeMarkAtRange

removeMarkAtRange(range: Selection, mark: Mark) => Transform
removeMarkAtRange(range: Selection, properties: Object) => Transform
removeMarkAtRange(range: Selection, type: String) => Transform

Remove a mark from the characters in a range. For convenience, you can pass a type string or properties object to implicitly create a Mark of that type.

toggleMarkAtRange

toggleMarkAtRange(range: Selection, mark: Mark) => Transform
toggleMarkAtRange(range: Selection, properties: Object) => Transform
toggleMarkAtRange(range: Selection, type: String) => Transform

Add or remove a mark from the characters in a range, depending on whether any of them already have the mark. For convenience, you can pass a type string or properties object to implicitly create a Mark of that type.

unwrapBlockAtRange

unwrapBlockAtRange(range: Selection, properties: Object) => Transform
unwrapBlockAtRange(range: Selection, type: String) => Transform

Unwrap all Block nodes in a range that match properties. For convenience, you can pass a type string or properties object.

unwrapInlineAtRange

unwrapInlineAtRange(range: Selection, properties: Object) => Transform
unwrapInlineAtRange(range: Selection, type: String) => Transform

Unwrap all Inline nodes in a range that match properties. For convenience, you can pass a type string or properties object.

wrapBlockAtRange

wrapBlockAtRange(range: Selection, properties: Object) => Transform
wrapBlockAtRange(range: Selection, type: String) => Transform

Wrap the Block nodes in a range with a new Block node with properties. For convenience, you can pass a type string or properties object.

wrapInlineAtRange

wrapInlineAtRange(range: Selection, properties: Object) => Transform
wrapInlineAtRange(range: Selection, type: String) => Transform

Wrap the Inline nodes in a range with a new Inline node with properties. For convenience, you can pass a type string or properties object.

wrapTextAtRange

wrapTextAtRange(range: Selection, prefix: String, [suffix: String]) => Transform

Surround the text in a range with prefix and suffix strings. If the suffix is ommitted, the prefix will be used instead.

History Transforms

redo

redo() => Transform

Move forward one step in the history.

undo

undo() => Transform

Move backward one step in the history.