​

Blocks API

​

Accessing the API

import { Blocks } from '@yoopta/editor';

Blocks.insertBlock(editor, 'Paragraph', { at: 0 });
Blocks.deleteBlock(editor, { at: 3 });
Blocks.moveBlock(editor, 'block-id', 5);

​

Type Definitions

type YooptaPathIndex = number;

type YooptaBlockData = {
  id: string;
  type: string;
  value: SlateElement[];
  meta: {
    order: number;
    depth: number;
    align?: 'left' | 'center' | 'right';
  };
};

​

Methods

​

insertBlock

Blocks.insertBlock(
  editor: YooEditor,
  type: string,
  options?: InsertBlockOptions
): string

• editor — Editor instance (required).
• type — Block type, e.g. 'Paragraph', 'Heading' (required).
• options.at — Position to insert; default: editor.path.current.
• options.focus — Whether to focus the block after insertion.
• options.blockData — Custom block data (id, meta, value).
• options.elements — Custom element structure via editor.y().

const blockId = Blocks.insertBlock(editor, 'Paragraph', {
  at: editor.path.current,
  focus: true,
});

​

deleteBlock

Blocks.deleteBlock(editor: YooEditor, options?: DeleteBlockOptions): void

• editor — Editor instance (required).
• options.at — Position of the block to delete.
• options.blockId — ID of the block to delete (overrides at if both set).
• options.focus — Whether to focus a block after deletion; default: true.
• options.focusTarget — Which block to focus: 'previous' | 'next' | 'none'; default: 'previous'.

Blocks.deleteBlock(editor, { at: 3, focusTarget: 'next' });

​

updateBlock

Blocks.updateBlock(
  editor: YooEditor,
  blockId: string,
  newData: Omit<Partial<YooptaBlockData>, 'id' | 'type'>
): void

• editor — Editor instance (required).
• blockId — ID of the block to update (required).
• newData.meta — Metadata to update: order, depth, align.
• newData.value — New block content (array of Slate elements).

Blocks.updateBlock(editor, 'block-123', {
  meta: { align: 'center' },
});

​

getBlock

Blocks.getBlock(editor: YooEditor, options: GetBlockOptions): YooptaBlockData | null

• editor — Editor instance (required).
• options.at — Position index of the block.
• options.id — ID of the block (overrides at if both set). One of at or id is required.

const block = Blocks.getBlock(editor, { id: 'block-123' });

​

moveBlock

Blocks.moveBlock(
  editor: YooEditor,
  draggedBlockId: string,
  newPath: number
): void

• editor — Editor instance (required).
• draggedBlockId — ID of the block to move (required).
• newPath — New position (order index) for the block (required).

Blocks.moveBlock(editor, 'block-123', 5);

​

focusBlock

Blocks.focusBlock(
  editor: YooEditor,
  blockId: string,
  options?: FocusBlockOptions
): void

• editor — Editor instance (required).
• blockId — ID of the block to focus (required).
• options.waitExecution — Delay focus (e.g. until DOM is ready).
• options.waitExecutionMs — Delay in milliseconds.
• options.shouldUpdateBlockPath — Update editor.path.current; default: true.
• options.focusAt — Cursor position: Point or Path; default: first node.
• options.slate — Slate editor instance to use (optional).

Blocks.focusBlock(editor, 'block-123', { focusAt: { path: [0, 0], offset: 5 } });

​

duplicateBlock

Blocks.duplicateBlock(
  editor: YooEditor,
  options?: DuplicateBlockOptions
): string | undefined

• editor — Editor instance (required).
• options.at — Position of the block to duplicate; default: editor.path.current.
• options.blockId — ID of the block to duplicate (overrides at).
• options.insertAt — Position to insert the duplicate; default: after original.
• options.focus — Focus the new block after creation; default: true.
• options.elements — Custom element structure for the duplicate.

const newId = Blocks.duplicateBlock(editor, { at: 2, insertAt: 4 });

​

splitBlock

Blocks.splitBlock(
  editor: YooEditor,
  options?: SplitBlockOptions
): string | undefined

• editor — Editor instance (required).
• options.at — Position of the block to split; default: editor.path.current.
• options.blockId — ID of the block to split.
• options.splitAt — Location to split at; default: current selection.
• options.focus — Focus after split; default: true.
• options.focusTarget — Which block to focus: 'new' | 'original' | 'none'; default: 'new'.
• options.preserveContent — Keep content in both blocks; default: true.

const newBlockId = Blocks.splitBlock(editor, { focusTarget: 'new' });

​

mergeBlock

Blocks.mergeBlock(editor: YooEditor, options?: MergeBlockOptions): void

• editor — Editor instance (required).
• options.at — Position of the source block (the one merged into target).
• options.blockId — ID of the source block.
• options.targetAt — Position of the target block (receives content); default: previous block.
• options.targetBlockId — ID of the target block.
• options.focus — Focus the target block after merge; default: true.
• options.preserveContent — Keep content from source block; default: true.

Blocks.mergeBlock(editor, { at: 5, targetAt: 3 });

​

toggleBlock

Blocks.toggleBlock(
  editor: YooEditor,
  type: string,
  options?: ToggleBlockOptions
): string

• editor — Editor instance (required).
• type — Target block/element type, e.g. 'Heading', 'Paragraph' (required).
• options.at — Position of the block; default: editor.path.current.
• options.scope — 'auto' (default) | 'block' (transform block) | 'element' (insert in leaf).
• options.preserveContent — Transfer text to new block/element; default: true.
• options.focus — Focus after toggle; default: false.
• options.elements — Custom element structure via editor.y().

Blocks.toggleBlock(editor, 'Heading', { preserveContent: true });

​

increaseBlockDepth

Blocks.increaseBlockDepth(
  editor: YooEditor,
  options?: BlockDepthOptions
): void

• editor — Editor instance (required).
• options.at — Position of the block; default: editor.path.current.
• options.blockId — ID of the block (overrides at).

Blocks.increaseBlockDepth(editor, { at: editor.path.current });

​

decreaseBlockDepth

Blocks.decreaseBlockDepth(
  editor: YooEditor,
  options?: BlockDepthOptions
): void

• editor — Editor instance (required).
• options.at — Position of the block; default: editor.path.current.
• options.blockId — ID of the block (overrides at).

Blocks.decreaseBlockDepth(editor, { blockId: 'block-123' });

​

getBlockSlate

Blocks.getBlockSlate(
  editor: YooEditor,
  options: GetBlockSlateOptions
): SlateEditor | null

• editor — Editor instance (required).
• options.at — Position of the block.
• options.id — ID of the block (overrides at). One of at or id is required.

const slate = Blocks.getBlockSlate(editor, { id: 'block-123' });
if (slate) {
  const text = Editor.string(slate, []);
}

​

buildBlockData

Blocks.buildBlockData(block?: BuildBlockDataOptions): YooptaBlockData

• block.id — Block ID; if omitted, a unique ID is generated.
• block.type — Block type (plugin name); default: 'Paragraph'.
• block.value — Block content (array of Slate elements).
• block.meta — Metadata: order, depth, align.

const blockData = Blocks.buildBlockData({
  type: 'Heading',
  meta: { order: 0, depth: 0, align: 'center' },
});