Skip to main content
Automatically tracks block-level nodes with unique IDs for precise document manipulation. Essential for collaborative editing, change tracking, and programmatic document updates.

​
How It Works

Every block-level node (paragraphs, headings, etc.) automatically receives a unique sdBlockId attribute. This enables:
  1. Precise targeting - Manipulate specific blocks even as document changes
  2. Change tracking - Know exactly which blocks were modified
  3. Collaborative editing - Reference blocks consistently across clients
  4. Programmatic updates - Update document structure via APIs

​
Use Case

  • Document APIs - Build REST APIs that manipulate specific blocks
  • Collaboration - Track who edited which blocks in real-time
  • Comments & Annotations - Attach metadata to specific blocks
  • Version Control - Diff documents at the block level
  • Templates - Replace placeholder blocks with dynamic content

​
Commands

​
replaceBlockNodeById

Replace a block node by its ID with new content
The replacement node should have the same type as the original
Example: 
const newParagraph = editor.schema.nodes.paragraph.create({}, editor.schema.text('New content'))
editor.commands.replaceBlockNodeById('block-123', newParagraph)
Parameters:
​
id
string
required
The sdBlockId of the node to replace
​
contentNode
ProseMirrorNode
required
The replacement ProseMirror node

​
deleteBlockNodeById

Delete a block node by its ID
Completely removes the node from the document
Example: 
editor.commands.deleteBlockNodeById('block-123')
Parameters:
​
id
string
required
The sdBlockId of the node to delete

​
updateBlockNodeAttributes

Update attributes of a block node by its ID
Merges new attributes with existing ones
Example: 
editor.commands.updateBlockNodeAttributes('block-123', { textAlign: 'center' })
Parameters:
​
id
string
required
The sdBlockId of the node to update
​
attrs
Object
required
Attributes to update

​
Helpers

​
getBlockNodes

Get all block nodes in the document Example: 
const blocks = editor.helpers.blockNode.getBlockNodes()
console.log(`Found ${blocks.length} block nodes`)
Returns:
​
return
Array<BlockNodeInfo>
required
See BlockNodeInfo type definition

​
getBlockNodeById

Get a specific block node by its ID Example: 
const block = editor.helpers.blockNode.getBlockNodeById('block-123')
if (block.length) console.log('Found:', block[0].node.type.name)
Parameters:
​
id
string
required
The sdBlockId to search for
Returns:
​
return
Array<BlockNodeInfo>
required
See BlockNodeInfo type definition

​
getBlockNodesByType

Get all block nodes of a specific type Example: 
const paragraphs = editor.helpers.blockNode.getBlockNodesByType('paragraph')
const headings = editor.helpers.blockNode.getBlockNodesByType('heading')
Parameters:
​
type
string
required
The node type name (e.g., ‘paragraph’, ‘heading’)
Returns:
​
return
Array<BlockNodeInfo>
required
See BlockNodeInfo type definition

​
getBlockNodesInRange

Get all block nodes within a position range Example: 
const selection = editor.state.selection
const blocksInSelection = editor.helpers.blockNode.getBlockNodesInRange(
  selection.from,
  selection.to
)
Parameters:
​
from
number
required
Start position
​
to
number
required
End position
Returns:
​
return
Array<BlockNodeInfo>
required
See BlockNodeInfo type definition

​
Types

​
BlockNodeInfo

Block node information object

​
Source Code