Manipulating Blocks

BlockNote operates on a block-based architecture, where all content is organized into discrete blocks. Understanding how to manipulate these blocks is fundamental to working with BlockNote effectively.

Block-Based Architecture

In BlockNote, everything is a block. A paragraph is a block, a heading is a block, a list item is a block, and even complex structures like tables are composed of blocks. This unified approach makes block manipulation consistent and predictable.

Blocks can be:

• Top-level blocks - Direct children of the document
• Nested blocks - Children of other blocks (like list items within a list)
• Different types - Paragraphs, headings, lists, tables, code blocks, etc.

Core Block Operations

BlockNote provides a comprehensive set of operations for manipulating blocks, all working at the block level:

Reading Blocks

• Get the entire document - Retrieve all top-level blocks
• Get specific blocks - Access individual blocks by ID or reference
• Navigate relationships - Find previous, next, or parent blocks
• Traverse all blocks - Iterate through the entire document structure

Creating Blocks

• Insert new blocks - Add blocks before or after existing ones
• Create complex structures - Build nested blocks like lists and tables
• Generate blocks programmatically - Create blocks from data or user input

Modifying Blocks

• Update existing blocks - Change block type, content, or properties
• Replace blocks - Swap one or more blocks with new blocks
• Move blocks - Reorder blocks by moving them up or down
• Nest and unnest - Change the hierarchy by indenting or outdenting blocks

Removing Blocks

• Delete specific blocks - Remove individual blocks or groups of blocks
• Clear selections - Remove blocks based on user selection

High-Level vs Low-Level APIs

BlockNote provides multiple layers of APIs for block manipulation:

High-Level APIs (Recommended)

The high-level APIs are designed to be intuitive and handle common use cases:

• Block manipulation methods - insertBlocks(), updateBlock(), removeBlocks(), etc.
• Selection-based operations - Work with user selections and cursor positions
• Automatic ID generation - No need to manually manage block identifiers
• Built-in validation - Ensures operations are safe and consistent

Low-Level APIs (Advanced)

For advanced use cases, BlockNote exposes lower-level APIs:

• ProseMirror transactions - Direct access to the underlying editor state
• Custom commands - Execute ProseMirror commands for specialized operations
• Manual state management - Full control over the editor's internal state

Recommendation: Start with the high-level APIs. They're easier to use, less error-prone, and handle most common scenarios. Only use low-level APIs when you need specialized functionality that isn't available at the higher level.

Common Block Patterns

Block Creation

// Insert a simple paragraph block
editor.insertBlocks(
  [{ type: "paragraph", content: "Hello, world!" }],
  referenceBlock,
);

// Create a complex block structure
editor.insertBlocks(
  [
    { type: "heading", content: "My Heading" },
    { type: "paragraph", content: "Some content" },
    { type: "bulletListItem", content: "List item 1" },
    { type: "bulletListItem", content: "List item 2" },
  ],
  referenceBlock,
);

Block Updates

// Change a block's type
editor.updateBlock(blockId, { type: "heading" });

// Update block content and properties
editor.updateBlock(blockId, {
  content: "Updated content",
  props: { level: 2 },
});

Block Removal

// Remove specific blocks
editor.removeBlocks([blockId1, blockId2]);

// Replace blocks with new blocks
editor.replaceBlocks(
  [oldBlockId],
  [{ type: "paragraph", content: "New content" }],
);

Best Practices

1. Use the highest-level API possible - Start with block manipulation methods before reaching for low-level APIs
2. Work with block references - Use existing blocks as references for positioning new blocks
3. Handle errors gracefully - Operations can fail if blocks don't exist or are invalid
4. Group related operations - Use transactions to group multiple block changes into a single undo/redo operation
5. Consider user experience - Think about how your block manipulations affect the user's workflow

Next Steps

This overview covers the fundamental concepts of block manipulation in BlockNote. For detailed API reference and specific examples, see:

• Manipulating Blocks Reference - Complete API documentation
• Cursor & Selections - Working with user selections
• Block Types - Understanding different block types and their properties