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
sdBlockId is regenerated on every document load. If you need cross-session block references (e.g., headless CLI pipelines, multi-step AI workflows), use the Document API instead. editor.doc.find() returns addresses whose nodeId prefers DOCX-native paraId for imported blocks. This is best-effort stable, not a permanent global ID: Word or other tools can rewrite IDs during structural changes, and SuperDoc may rewrite duplicates on import.

​
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)

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    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')

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    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' })

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    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`)

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    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)

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    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')

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    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
)

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    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