Overview
The splitBlock method splits a block at the cursor position, creating a new block with the content after the split point.
Signature
Blocks.splitBlock(
editor: YooEditor,
options?: SplitBlockOptions
): string | undefined
Parameters
Configuration object for splitting
at
number
default:"editor.path.current"
Position of the block to split
Specific position to split at. If not provided, uses current selection.
Whether to focus after split
focusTarget
'new' | 'original' | 'none'
default:"'new'"
Which block to focus after split:
'new' - Focus the new block (default)'original' - Focus the original block'none' - Don’t focus anything
Whether to preserve content in both blocks. If false, the new block will be empty.
Return Value
Returns the ID of the newly created block, or undefined if split failed.
Examples
Basic Usage
import { Blocks } from '@yoopta/editor';
// Split current block at selection
const newBlockId = Blocks.splitBlock(editor);
// Split specific block
const newBlockId = Blocks.splitBlock(editor, { at: 3 });
// Split and focus original block
const newBlockId = Blocks.splitBlock(editor, {
focusTarget: 'original',
});
Split at Specific Position
import { Point } from 'slate';
// Split at specific point
const newBlockId = Blocks.splitBlock(editor, {
splitAt: { path: [0, 5], offset: 10 },
});
Split Without Preserving Content
// Create empty block after split
const newBlockId = Blocks.splitBlock(editor, {
preserveContent: false,
});
Use Cases
Split on Enter Key
const handleEnterKey = (editor: YooEditor) => {
const newBlockId = Blocks.splitBlock(editor, {
focusTarget: 'new',
});
if (newBlockId) {
Blocks.focusBlock(editor, newBlockId);
}
};
const splitAndTransform = (editor: YooEditor, newType: string) => {
const newBlockId = Blocks.splitBlock(editor);
if (newBlockId) {
Blocks.toggleBlock(editor, newType, {
at: Blocks.getBlock(editor, { id: newBlockId })?.meta.order,
});
}
};
Notes
The split preserves content by default. Content before the split point stays in the original block, content after goes to the new block.
If there’s no selection and splitAt is not provided, the method will return undefined.
The new block is inserted right after the original block and has the same type.
Splitting void blocks or blocks that don’t support splitting may cause unexpected behavior.
The method handles text nodes intelligently - if splitting in the middle of a text node, it will split the text appropriately.
Type Definition
type SplitBlockOptions = {
at?: number; // YooptaPathIndex
blockId?: string;
splitAt?: Location;
focus?: boolean;
focusTarget?: 'new' | 'original' | 'none';
preserveContent?: boolean;
};
