Skip to main content

​
Overview

The insertBlock method creates and inserts a new block of the specified type into the editor at a given position.

​
Signature

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

​
Parameters

​
editor
YooEditor
required
The editor instance
​
type
string
required
Type of block to insert (must be a registered plugin type, e.g., ‘Paragraph’, ‘Heading’, ‘Accordion’)
​
options
InsertBlockOptions
Configuration object for inserting the block

​
Return Value

Returns the id of the newly created block.

​
Examples

​
Basic Usage

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

function MyComponent() {
  const editor = useYooptaEditor();

  const addParagraph = () => {
    // Insert paragraph at current position
    const blockId = Blocks.insertBlock(editor, 'Paragraph', {
      at: editor.path.current,
      focus: true,
    });
  };

  return <button onClick={addParagraph}>Add Paragraph</button>;
}

​
Insert at Specific Position

// Insert at beginning
Blocks.insertBlock(editor, 'Heading', {
  at: 0,
  focus: true,
});

// Insert at specific index
Blocks.insertBlock(editor, 'Paragraph', {
  at: 5,
});

​
Insert with Custom Content

// Insert heading with custom text
Blocks.insertBlock(editor, 'Heading', {
  elements: editor.y('heading-one', {
    children: [editor.y.text('My Custom Heading')]
  }),
  focus: true,
});

// Insert accordion with custom structure
Blocks.insertBlock(editor, 'Accordion', {
  elements: editor.y('accordion-list', {
    children: [
      editor.y('accordion-list-item', {
        props: { isExpanded: true },
        children: [
          editor.y('accordion-list-item-heading', {
            children: [editor.y.text('Item 1')]
          }),
          editor.y('accordion-list-item-content')
        ]
      })
    ]
  }),
});

​
Insert with Custom Block Data

// Insert with custom ID and meta
Blocks.insertBlock(editor, 'Paragraph', {
  blockData: {
    id: 'custom-block-id',
    meta: {
      align: 'center',
      depth: 1,
    },
  },
});

​
Use Cases

​
Add Block After Current

const addBlockAfter = (editor: YooEditor, type: string) => {
  const currentPath = editor.path.current;
  const nextPath = currentPath + 1;
  
  return Blocks.insertBlock(editor, type, {
    at: nextPath,
    focus: true,
  });
};

​
Insert Multiple Blocks

const insertMultipleBlocks = (editor: YooEditor, types: string[]) => {
  const blockIds: string[] = [];
  let currentPath = editor.path.current;

  types.forEach((type) => {
    const blockId = Blocks.insertBlock(editor, type, {
      at: currentPath,
      focus: false,
    });
    blockIds.push(blockId);
    currentPath += 1;
  });

  // Focus last inserted block
  if (blockIds.length > 0) {
    const lastBlock = Blocks.getBlock(editor, { id: blockIds[blockIds.length - 1] });
    if (lastBlock) {
      Blocks.focusBlock(editor, lastBlock.id);
    }
  }

  return blockIds;
};

​
Insert Block with Plugin Lifecycle

// The insertBlock method automatically calls plugin lifecycle hooks:
// - beforeCreate: called before block creation
// - onCreate: called after block creation

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

// Plugin's onCreate hook will be called automatically

​
Notes

The type parameter must match a plugin type that is registered in the editor. If the plugin doesn’t exist, an error will be thrown.
If elements is not provided, the method will use the plugin’s default structure (from beforeCreate hook or buildBlockElementsStructure).
When focus is true, the editor will focus the newly created block, allowing immediate user interaction.
Inserting a block at an invalid position (e.g., negative number or beyond array length) may cause unexpected behavior. Always validate the position before insertion.
The method automatically generates a unique ID for the block if not provided in blockData.id. The block’s meta.order is set based on the at parameter.

​
Type Definition

type InsertBlockOptions = {
  at?: number; // YooptaPathIndex
  focus?: boolean;
  blockData?: Omit<Partial<YooptaBlockData>, 'type'>;
  elements?: SlateElement;
};

deleteBlock

Remove inserted block

updateBlock

Modify block after insertion

duplicateBlock

Clone existing block

getBlock

Get block after insertion