Slate Utils
API reference for @udecode/slate-utils.
@udecode/slate-utils contains utility functions for Slate.
Queries
findDescendant
Iterates through all nodes in the editor and returns the first match. If no match is found, returns undefined.
Parameters
The editor to search for the descendant node.
The options to find the node. It can contain match condition, starting location, whether to traverse in reverse, and whether to include voids.
Returns
Returns the first node entry matching the condition or undefined if no match
is found.
getBlockAbove
Returns the block above a specified location
- Default: Selection.
Parameters
The editor to search for the block.
The options to find the block above a location.
Returns
Returns the block above the specified location.
getBlocks
Retrieves block-level node entries from the editor.
Parameters
The editor to search for block-level nodes.
Options for getting node entries.
Returns
An array of block-level node entries.
getChildren
Returns the children node entries of a node entry.
Parameters
The node entry to get its children.
Returns
Returns an array of the children node entries.
getEdgeBlocksAbove
Returns the edge blocks above a specified location.
- Default: Selection.
Parameters
The editor to search for the edge blocks.
The options to find the edge blocks above a location.
Returns
Returns an array containing the start block and end block above the specified
location, or null if not found.
getFragmentProp
Retrieves a consistent property value from a fragment of nodes.
Parameters
The fragment of nodes to search for the property.
Returns
The consistent property value found in the fragment, or undefined if no consistent value is found.
getFirstNodeText
Gets the first text node from a node.
Parameters
The root node to search for text nodes.
Options for getting node texts.
Returns
Returns the first text node entry or undefined if no text nodes are found.
getLastChild
Returns the last child of a node or null if no children.
Parameters
The node entry to get its last child.
Returns
Returns the last child of a node or null if no children.
getLastNodeByLevel
Retrieves the last node at a specified level in the editor.
Parameters
The editor to search for the last node.
The level at which to find the last node.
Returns
Returns the last node entry at the specified level or undefined if no node
is found.
getMark
Retrieves the value of the selection mark by key in the editor.
Parameters
The editor where the selection mark is located.
The key of the selection mark to retrieve.
Returns
Returns the value of the selection mark or undefined if the editor or the
mark is not found.
getNextNodeStartPoint
Retrieves the start point of the next node at a specified path in the editor.
Parameters
The editor to search for the next node.
The path at which to find the next node.
Returns
Returns the start point of the next node or undefined if the next node is
not found.
getNextSiblingNodes
Retrieves the sibling nodes following a specified path in the ancestor node.
Parameters
The ancestor node of the sibling nodes.
The path of the reference node.
Returns
Returns an array of sibling nodes after the path or an empty array if no sibling nodes are found.
getOperations
Retrieves the operations of the editor.
Parameters
The editor to get its operations.
Returns
Returns the operations of the editor as TOperation array.
getPointBeforeLocation
Returns the point before a location, with additional options to customize the behavior. If no options are provided or neither match nor matchString are defined, it will default to using getPointBefore.
Parameters
The editor where to find the point before a location.
The location where to start.
The options to define how the search is performed.
Returns
Returns the point before a location. If not found, returns undefined.
getPointFromLocation
Returns the point from a location (Default: selection). If the location is a range, it gets the anchor point. If the location is a path, it gets the point at this path with offset 0.
Parameters
The editor where to find the point.
Returns
Returns the point from the location.
getPointNextToVoid
If the start point is inside an inline void, returns the point before or after it.
Parameters
The editor where to find the point next to the void.
Returns
Returns the point next to the void.
getPreviousBlockById
Finds the block before a block by ID. If not found, it finds the first block by ID and returns [null, its previous path].
Parameters
The editor where to find the previous block.
The ID of the block.
The options for the node query.
Returns
Returns the node entry of the previous block if found, otherwise undefined.
getPreviousNodeEndPoint
Gets the end point of the previous node.
Parameters
The editor where to find the previous node's end point.
The path where to start the search.
Returns
Returns the end point of the previous node if found, otherwise undefined.
getPreviousPath
Generates the previous path based on the given path.
Parameters
The current path.
Returns
The previous path or undefined if there is no previous path.
getPreviousSiblingNode
Gets the previous sibling node from the given path.
Parameters
The editor instance.
The current path.
Returns
An array containing the previous sibling node and its path, or undefined if
there is no previous sibling.
getRangeBefore
Gets the range from the point before a given location to the end point of the location.
Parameters
The editor instance.
The location to consider.
Options for getting the point before the location.
Returns
The range from the point before the location to the end point of the location,
or undefined if no such point exists.
getRangeFromBlockStart
Gets the range from the start of the block above a location to the location.
Parameters
The editor instance.
Options for getting the block above the location.
Returns
The range from the start of the block above the location to the location, or
undefined if no such block exists.
getSelectionFragment
Retrieves the fragment of the current selection, optionally unwrapping structural nodes.
Parameters
The editor to get the selection fragment from.
Returns
An array of TElement representing the fragment of the current selection. Returns an empty array if the selection is not expanded or if no fragment is found.
getSelectionText
Gets the selected text from the editor.
Parameters
The editor instance.
Returns
The selected text, or an empty string if no text is selected.
isAncestorEmpty
Checks whether an ancestor node is empty (has empty text and no inline children).
Parameters
The editor instance.
The ancestor node to check.
Returns
True if the ancestor node is empty, false otherwise.
isBlockAboveEmpty
Checks whether the block above the selection is empty.
Parameters
The editor instance.
Returns
True if the block above the selection is empty, false otherwise.
isBlockTextEmptyAfterSelection
Checks whether the text in the block after the selection is empty.
Parameters
The editor instance.
Returns
True if the text in the block after the selection is empty, false otherwise.
isDocumentEnd
Checks whether the selection is at the end of the document.
Parameters
The editor instance.
Returns
True if the selection is at the end of the document, false otherwise.
isFirstChild
Checks whether a node is the first child of its parent.
Parameters
The path of the node to check.
Returns
True if the node is the first child of its parent, false otherwise.
isMarkActive
Checks whether a mark is active in the selection.
Parameters
The editor instance.
The mark key.
Returns
True if the mark is active in the selection.
isPointAtWordEnd
Checks whether a point is at the end of a word.
Parameters
The editor instance.
The point to check.
Returns
True if the point is at the end of a word, false otherwise.
isRangeAcrossBlocks
Determines whether the range (Default: selection) is across blocks.
Parameters
The editor instance.
The range to check. If not provided, the selection range is used.
Returns
True if the range is across blocks, false if it's within a single block, or undefined if the block was not found.
isRangeInSameBlock
Determines whether the range is within the same block.
Parameters
The editor instance.
The range to check. If not provided, the selection range is used.
Returns
True if the range is within the same block, false otherwise.
isRangeInSingleText
Checks whether a range is within a single text path.
Parameters
The range to check.
Returns
True if the range is within a single text path, false otherwise.
isSelectionAtBlockEnd
Checks whether the selection focus is at the end of its parent block.
Parameters
The editor instance.
The options object.
Returns
True if the selection focus is at the end of its parent block, false otherwise.
isSelectionAtBlockStart
Checks whether the selection anchor or focus is at the start of its parent block.
Parameters
The editor instance.
The options object.
Returns
True if the selection anchor or focus is at the start of its parent block, false otherwise.
isSelectionExpanded
Checks whether the selection is expanded.
Parameters
The editor instance.
Returns
True if the selection is expanded, false otherwise.
isTextByPath
Checks whether the node at a given path is a text node.
Parameters
The editor instance.
The path to the node to check.
Returns
True if the node is a text node, false otherwise.
isWordAfterTrigger
Checks whether the word at a given point is after a trigger (punctuation character).
Parameters
The editor instance.
The point to check.
The trigger character to check for.
Returns
An object containing the range from the point before the start of the previous word to the given point, and a match if the text at the range starts with the trigger and ends with word characters.
queryEditor
Queries the editor state.
Parameters
The editor instance.
The options object, which can include a filter function, selectionAtBlockStart, selectionAtBlockEnd, allow, exclude, and at properties.
Returns
True if the editor state matches the query, false otherwise.
Transforms
duplicateBlocks
Duplicates the given blocks and inserts them after the last block in the selection.
Parameters
The editor instance.
An array of node entries representing the blocks to duplicate.
insertElements
Inserts nodes at a location in the document.
Parameters
The editor instance.
The nodes to insert.
The options object.
insertEmptyElement
Inserts an empty element at a location in the document.
Parameters
The editor instance.
The type of the element to insert.
The options object.
moveChildren
Moves the children of a node to a path.
Parameters
The editor instance.
The options object, which includes at, to, match, and fromStartIndex
properties.
Returns
The number of children moved.
removeEditorText
Removes all non-empty text nodes from the editor.
Parameters
The editor instance.
Options for removing nodes. The match function in options will be combined with the text length check.
removeMark
Removes a mark and triggers onChange if the selection is collapsed.
Parameters
The editor instance.
The options object, which includes key, at, and shouldChange
properties.
removeNodeChildren
Removes all children of a node.
Parameters
The editor instance.
The path to the node to remove children from.
The options object.
removeSelectionMark
Removes all marks from the selection.
Parameters
The editor instance.
replaceNodeChildren
Replaces the children of a node: removes then inserts them.
Parameters
The editor instance.
The options object, which includes at, nodes, insertOptions, and
removeOptions properties.
selectEndOfBlockAboveSelection
Selects the end point of the block above the selection.
Parameters
The editor instance.
selectNodes
Selects the range encompassing the given nodes.
Parameters
The editor instance.
An array of node entries to select.
setBlockAboveNode
Sets properties on the block above the current selection.
Parameters
The editor instance.
The properties to set on the block.
Options for setting nodes, excluding the 'at' property.
setBlockAboveTexts
Sets properties on the lowest-level nodes within the block above the current selection.
Parameters
The editor instance.
The properties to set on the text nodes.
Options for setting nodes, excluding the 'at' property.
setBlockNodes
Sets properties on all block nodes that match the given options.
Parameters
The editor instance.
The properties to set on the matching block nodes.
Options for getting node entries to update.
setMarks
Sets marks to selected text.
Parameters
The editor instance.
The marks to set.
Marks to clear.
toggleMark
Adds or removes marks in the selection.
Parameters
The editor instance.
The options object, which includes key and clear properties.
toggleWrapNodes
Unwraps a node if the node type is in selection, otherwise wraps it.
Parameters
The editor instance.
The type of the node.
wrapNodeChildren
Wraps the children of a node into a single element.
Parameters
The editor instance.
The new parent element.
The options object, which includes at property.
Utils
createDocumentNode
Creates a new document node.
Parameters
- Default:
'p' - Default: an empty string.
- Default: an empty array.
The type of the node.
The text for the node.
The remaining nodes.
Returns
An array of TDescendant nodes, starting with the newly created node.
createNode
Creates a new node.
Parameters
- Default:
'p' - Default: an empty string.
The type of the node.
The text for the node.
Returns
A new TElement node.