Skip to main content
Available since v0.10.0
Field Annotation use is not recommended because of its limited support for advanced document content (e.g., tables, advanced styling). Use the more versatile Structured Content Fields.

​
Configuration

​
handleDropOutside
boolean
default:"false"
Handle drops outside editor viewport
​
annotationClass
string
default:"'annotation'"
CSS class for field styling
​
borderColor
string
default:"'#b015b3'"
Default field border color

​
Usage

Basic Setup: 
import { SuperDoc } from 'superdoc';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  // Field annotations are included by default via getStarterExtensions().
  // Configure options here:
  fieldAnnotation: {
    handleDropOutside: true,
    borderColor: '#b015b3',
  },
});
Form Template Workflow: 
// 1. Create form fields
const fields = [
  { id: 'name', label: 'Full Name', type: 'text' },
  { id: 'date', label: 'Date', type: 'text' },
  { id: 'signature', label: 'Sign Here', type: 'signature' }
];

// 2. Insert fields into document
fields.forEach((field, i) => {
  editor.commands.addFieldAnnotation(i * 100, {
    fieldId: field.id,
    displayLabel: field.label,
    type: field.type
  });
});

// 3. Handle user interactions
editor.on('fieldAnnotationClicked', ({ node }) => {
  openFieldEditor(node.attrs.fieldId);
});

// 4. Fill and export
editor.annotate([
  { input_id: 'name', input_value: 'John Doe' },
  { input_id: 'date', input_value: '2024-01-15' }
]);

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // 1. Create form fields
    const fields = [
      { id: 'name', label: 'Full Name', type: 'text' },
      { id: 'date', label: 'Date', type: 'text' },
      { id: 'signature', label: 'Sign Here', type: 'signature' }
    ];

    // 2. Insert fields into document
    fields.forEach((field, i) => {
      editor.commands.addFieldAnnotation(i * 100, {
        fieldId: field.id,
        displayLabel: field.label,
        type: field.type
      });
    });

    // 3. Handle user interactions
    editor.on('fieldAnnotationClicked', ({ node }) => {
      openFieldEditor(node.attrs.fieldId);
    });

    // 4. Fill and export
    editor.annotate([
      { input_id: 'name', input_value: 'John Doe' },
      { input_id: 'date', input_value: '2024-01-15' }
    ]);
  },
});

​
Commands

​
findFieldAnnotations

Find field annotations matching a predicate function
Added in v0.10.3
// Find all signature fields
const signatureFields = findFieldAnnotations(
  node => node.attrs.type === 'signature',
  state
);

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Find all signature fields
    const signatureFields = findFieldAnnotations(
      node => node.attrs.type === 'signature',
      editor.state
    );
  },
});

// Find fields with specific color
const redFields = findFieldAnnotations(
  node => node.attrs.fieldColor === '#FF0000',
  state
);

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Find fields with specific color
    const redFields = findFieldAnnotations(
      node => node.attrs.fieldColor === '#FF0000',
      editor.state
    );
  },
});
Parameters:
​
predicate
function
required
Function to test each annotation node
​
state
EditorState
required
ProseMirror editor state
Returns:
​
result
Array
Matching field annotations

​
findFieldAnnotationsBetween

Find all field annotations between two positions 
// Find fields in selection
const { from, to } = state.selection;
const selectedFields = findFieldAnnotationsBetween(from, to, state.doc);

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Find fields in selection
    const { from, to } = editor.state.selection;
    const selectedFields = findFieldAnnotationsBetween(from, to, editor.state.doc);
  },
});

// Find fields in specific range
const rangeFields = findFieldAnnotationsBetween(100, 500, state.doc);
console.log(`Found ${rangeFields.length} fields in range`);

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Find fields in specific range
    const rangeFields = findFieldAnnotationsBetween(100, 500, editor.state.doc);
    console.log(`Found ${rangeFields.length} fields in range`);
  },
});
Parameters:
​
from
number
required
Start position
​
to
number
required
End position
​
doc
Node
required
ProseMirror document node
Returns:
​
result
Array
Field annotations in range

​
findFieldAnnotationsByFieldId

Find field annotations by field ID(s) 
// Find single field
const fields = findFieldAnnotationsByFieldId('field-123', state);

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Find single field
    const fields = findFieldAnnotationsByFieldId('field-123', editor.state);
  },
});

// Find multiple fields
const fields = findFieldAnnotationsByFieldId(['field-1', 'field-2'], state);
fields.forEach(({ pos, node }) => {
  console.log(`Found ${node.attrs.fieldId} at position ${pos}`);
});

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Find multiple fields
    const fields = findFieldAnnotationsByFieldId(['field-1', 'field-2'], editor.state);
    fields.forEach(({ pos, node }) => {
      console.log(`Found ${node.attrs.fieldId} at position ${pos}`);
    });
  },
});
Parameters:
​
fieldIdOrArray
string | Array.<string>
required
Single field ID or array of field IDs
​
state
EditorState
required
ProseMirror editor state
Returns:
​
result
Array
Matching field annotations

​
findFirstFieldAnnotationByFieldId

Find the first field annotation matching a field ID
Added in v0.10.2
const firstField = findFirstFieldAnnotationByFieldId('field-123', state);
if (firstField) {
  console.log(`First occurrence at position ${firstField.pos}`);
}

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    const firstField = findFirstFieldAnnotationByFieldId('field-123', editor.state);
    if (firstField) {
      console.log(`First occurrence at position ${firstField.pos}`);
    }
  },
});
Parameters:
​
fieldId
string
required
Field ID to search for
​
state
EditorState
required
ProseMirror editor state
Returns:
​
result
Object | null
First matching annotation or null

​
findHeaderFooterAnnotationsByFieldId

Find field annotations in headers and footers by field ID or array of field IDs.
Added in v0.11.2
const headerFooterAnnotations = findHeaderFooterAnnotationsByFieldId('field-123', editor, activeSectionEditor);
headerFooterAnnotations.forEach(({ node, pos }) => {
  console.log(`Field ${node.attrs.fieldId} at position ${pos}`);
});

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    const headerFooterAnnotations = findHeaderFooterAnnotationsByFieldId('field-123', editor, activeSectionEditor);
    headerFooterAnnotations.forEach(({ node, pos }) => {
      console.log(`Field ${node.attrs.fieldId} at position ${pos}`);
    });
  },
});
Parameters:
​
fieldIdOrArray
string | Array.<string>
required
The field ID or array of field IDs
​
editor
Editor
required
The main editor instance
​
activeSectionEditor
Editor
required
The currently active section editor
Returns:
​
result
Array
Array of field annotations with their positions

​
getAllFieldAnnotations

Get all field annotations in the document 
import { fieldAnnotationHelpers } from 'superdoc';
const { getAllFieldAnnotations } = fieldAnnotationHelpers;

const annotations = getAllFieldAnnotations(editor.state);
console.log(`Document contains ${annotations.length} field annotations`);

annotations.forEach(({ pos, node }) => {
  console.log(`Field ${node.attrs.fieldId} at position ${pos}`);
});
Parameters:
​
state
EditorState
required
ProseMirror editor state
Returns:
​
result
Array
Array of field annotations with positions

​
getAllFieldAnnotationsWithRect

Get all field annotations with their bounding rectangles
Added in v0.11.0
const annotationsWithRects = getAllFieldAnnotationsWithRect(view, state);
annotationsWithRects.forEach(({ node, rect }) => {
  console.log(`Field ${node.attrs.fieldId} at ${rect.left}, ${rect.top}`);
});

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    const annotationsWithRects = getAllFieldAnnotationsWithRect(editor.view, editor.state);
    annotationsWithRects.forEach(({ node, rect }) => {
      console.log(`Field ${node.attrs.fieldId} at ${rect.left}, ${rect.top}`);
    });
  },
});
Parameters:
​
view
EditorView
required
ProseMirror editor view
​
state
EditorState
required
ProseMirror editor state
Returns:
​
result
Array
Annotations with positions and rectangles

​
Delete & Remove

​
findRemovedFieldAnnotations

Find field annotation nodes that were removed in a transaction
Added in v0.11.2
const removedFields = findRemovedFieldAnnotations(transaction);
removedFields.forEach(({ node, pos }) => {
  console.log(`Field ${node.attrs.fieldId} at position ${pos}`);
});

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    const removedFields = findRemovedFieldAnnotations(transaction);
    removedFields.forEach(({ node, pos }) => {
      console.log(`Field ${node.attrs.fieldId} at position ${pos}`);
    });
  },
});
Parameters:
​
tr
Transaction
required
ProseMirror transaction to analyze
Returns:
​
result
Array
Array of removed field annotation nodes with their positions

​
deleteFieldAnnotations

Delete field annotations by field ID 
// Delete single field annotation
editor.commands.deleteFieldAnnotations('field-123')

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Delete single field annotation
    editor.commands.deleteFieldAnnotations('field-123')
  },
});

// Delete multiple field annotations
editor.commands.deleteFieldAnnotations(['field-1', 'field-2'])

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Delete multiple field annotations
    editor.commands.deleteFieldAnnotations(['field-1', 'field-2'])
  },
});
Parameters:
​
fieldIdOrArray
string | Array.<string>
required
Field ID or array of field IDs to delete
Returns: boolean Command success status

​
deleteFieldAnnotationsByNode

Delete field annotations by node references 
const annotations = editor.helpers.fieldAnnotation.getAllFieldAnnotations();
editor.commands.deleteFieldAnnotationsByNode(annotations.slice(0, 2));

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    const annotations = editor.helpers.fieldAnnotation.getAllFieldAnnotations();
    editor.commands.deleteFieldAnnotationsByNode(annotations.slice(0, 2));
  },
});
Parameters:
​
annotations
Array.<{pos: number, node: Node}>
required
Array of annotation objects to delete
Returns: boolean Command success status

​
deleteFieldAnnotation

Delete a single field annotation 
const annotation = editor.helpers.fieldAnnotation.findFieldAnnotationsByFieldId('field-123')[0];
editor.commands.deleteFieldAnnotation(annotation);

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    const annotation = editor.helpers.fieldAnnotation.findFieldAnnotationsByFieldId('field-123')[0];
    editor.commands.deleteFieldAnnotation(annotation);
  },
});
Parameters:
​
annotation
Object
required
Annotation object to delete
Returns: boolean Command success status

​
sliceFieldAnnotations

Delete a portion of annotations associated with a field 
// Remove annotations starting from index 6
editor.commands.sliceFieldAnnotations('field-123', 5)

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Remove annotations starting from index 6
    editor.commands.sliceFieldAnnotations('field-123', 5)
  },
});

// Remove from multiple fields
editor.commands.sliceFieldAnnotations(['field-1', 'field-2'], 5)

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Remove from multiple fields
    editor.commands.sliceFieldAnnotations(['field-1', 'field-2'], 5)
  },
});
Parameters:
​
fieldIdOrArray
string | Array.<string>
required
The field ID or array of field IDs
​
end
number
required
Index at which to end extraction
Returns: boolean Command success status

​
Create & Add

​
addFieldAnnotation

Add field annotation at specified position 
editor.commands.addFieldAnnotation(10, {
  fieldId: 'field-123',
  displayLabel: 'Enter your name',
  fieldType: 'TEXTINPUT',
  fieldColor: '#980043'
})

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    editor.commands.addFieldAnnotation(10, {
      fieldId: 'field-123',
      displayLabel: 'Enter your name',
      fieldType: 'TEXTINPUT',
      fieldColor: '#980043'
    })
  },
});
Parameters:
​
pos
number
required
Document position to insert annotation
​
attrs
Object
required
Field annotation attributes
​
editorFocus
boolean
Whether to focus editor after insertion
Returns: boolean Command success status

​
addFieldAnnotationAtSelection

Add field annotation at current selection position 
editor.commands.addFieldAnnotationAtSelection({
  fieldId: 'field-456',
  displayLabel: 'Signature here'
}, true)

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    editor.commands.addFieldAnnotationAtSelection({
      fieldId: 'field-456',
      displayLabel: 'Signature here'
    }, true)
  },
});
Parameters:
​
attrs
Object
default:"{}"
Field annotation attributes
​
editorFocus
boolean
Whether to focus editor after insertion
Returns: boolean Command success status

​
Update & Edit

​
replaceWithFieldAnnotation

Replace text ranges with field annotations 
editor.commands.replaceWithFieldAnnotation([{
  from: 20,
  to: 45,
  attrs: {
    fieldId: 'field-789',
    fieldType: 'TEXTINPUT',
    fieldColor: '#980043'
  }
}])

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    editor.commands.replaceWithFieldAnnotation([{
      from: 20,
      to: 45,
      attrs: {
        fieldId: 'field-789',
        fieldType: 'TEXTINPUT',
        fieldColor: '#980043'
      }
    }])
  },
});
Parameters:
​
fieldsArray
Array.<Object>
required
Array of field replacement objects
​
fieldsArray[]
object
required
Options object
Returns: boolean Command success status

​
replaceFieldAnnotationsWithLabelInSelection

Replace field annotations with text labels in current selection
Added in v0.11.0
// Replace all annotations in selection with their labels
editor.commands.replaceFieldAnnotationsWithLabelInSelection()

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Replace all annotations in selection with their labels
    editor.commands.replaceFieldAnnotationsWithLabelInSelection()
  },
});
Parameters:
​
options
Object
default:"{}"
Additional options
Returns: boolean Command success status

​
replaceFieldAnnotationsWithLabel

Replace field annotations with text labels
Added in v0.11.0
// Replace specific fields with labels
editor.commands.replaceFieldAnnotationsWithLabel(['field-1', 'field-2'])

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Replace specific fields with labels
    editor.commands.replaceFieldAnnotationsWithLabel(['field-1', 'field-2'])
  },
});

// Replace only text annotations in selection
editor.commands.replaceFieldAnnotationsWithLabel(null, {
  isInSelection: true,
  types: ['text']
})

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Replace only text annotations in selection
    editor.commands.replaceFieldAnnotationsWithLabel(null, {
      isInSelection: true,
      types: ['text']
    })
  },
});
Parameters:
​
fieldIdOrArray
string | Array.<string>
required
Field ID(s) to replace
​
options
Object
default:"{}"
Replace options
Returns: boolean Command success status

​
resetFieldAnnotations

Reset all field annotations to their default values 
// Reset all annotations in document
editor.commands.resetFieldAnnotations()

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Reset all annotations in document
    editor.commands.resetFieldAnnotations()
  },
});
Returns: boolean Command success status

​
updateFieldAnnotations

Update field annotations by field ID 
// Update single field
editor.commands.updateFieldAnnotations('field-123', {
  displayLabel: 'Updated label',
  fieldColor: '#FF0000'
})

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Update single field
    editor.commands.updateFieldAnnotations('field-123', {
      displayLabel: 'Updated label',
      fieldColor: '#FF0000'
    })
  },
});

// Update multiple fields
editor.commands.updateFieldAnnotations(['field-1', 'field-2'], {
  hidden: true
})

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Update multiple fields
    editor.commands.updateFieldAnnotations(['field-1', 'field-2'], {
      hidden: true
    })
  },
});
Parameters:
​
fieldIdOrArray
string | Array.<string>
required
Field ID or array of field IDs
​
attrs
Object
default:"{}"
Attributes to update
Returns: boolean Command success status

​
updateFieldAnnotation

Update a specific field annotation instance 
// Update specific annotation instance
const annotation = editor.helpers.fieldAnnotation.findFirstFieldAnnotationByFieldId('field-123', state);
editor.commands.updateFieldAnnotation(annotation, {
  displayLabel: 'New label'
})

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Update specific annotation instance
    const annotation = editor.helpers.fieldAnnotation.findFirstFieldAnnotationByFieldId('field-123', editor.state);
    editor.commands.updateFieldAnnotation(annotation, {
      displayLabel: 'New label'
    })
  },
});
Parameters:
​
annotation
Object
required
Annotation object with pos and node
​
attrs
Object
default:"{}"
Attributes to update
Returns: boolean Command success status

​
updateFieldAnnotationsAttributes

Update the attributes of annotations 
const annotations = editor.helpers.fieldAnnotation.getAllFieldAnnotations();
editor.commands.updateFieldAnnotationsAttributes(annotations, {
  fieldColor: '#FF0000',
  hidden: false
});

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    const annotations = editor.helpers.fieldAnnotation.getAllFieldAnnotations();
    editor.commands.updateFieldAnnotationsAttributes(annotations, {
      fieldColor: '#FF0000',
      hidden: false
    });
  },
});
Parameters:
​
annotations
Array.<{pos: number, node: Node}>
required
Array of annotations to update
​
attrs
object
default:"{}"
Attributes to update
Returns: boolean Command success status

​
setFieldAnnotationsHiddenByCondition

Hide field annotations based on a condition 
// Hide specific field IDs
editor.commands.setFieldAnnotationsHiddenByCondition(node => {
  const targetIds = ['field-1', 'field-2', 'field-3'];
  return targetIds.includes(node.attrs.fieldId);
})

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Hide specific field IDs
    editor.commands.setFieldAnnotationsHiddenByCondition(node => {
      const targetIds = ['field-1', 'field-2', 'field-3'];
      return targetIds.includes(node.attrs.fieldId);
    })
  },
});

// Hide signature fields and show others
editor.commands.setFieldAnnotationsHiddenByCondition(
  node => node.attrs.type === 'signature',
  true
)

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Hide signature fields and show others
    editor.commands.setFieldAnnotationsHiddenByCondition(
      node => node.attrs.type === 'signature',
      true
    )
  },
});
Parameters:
​
predicate
function
Function to test each annotation
​
unsetFromOthers
boolean
Whether to show non-matching annotations
Returns: boolean Command success status

​
unsetFieldAnnotationsHidden

Show all hidden field annotations 
// Make all annotations visible
editor.commands.unsetFieldAnnotationsHidden()

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Make all annotations visible
    editor.commands.unsetFieldAnnotationsHidden()
  },
});
Returns: boolean Command success status

​
setFieldAnnotationsVisibility

Set visibility for all field annotations 
// Make all annotations visible
editor.commands.setFieldAnnotationsVisibility('visible')

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Make all annotations visible
    editor.commands.setFieldAnnotationsVisibility('visible')
  },
});

// Hide all annotations (preserves layout)
editor.commands.setFieldAnnotationsVisibility('hidden')

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Hide all annotations (preserves layout)
    editor.commands.setFieldAnnotationsVisibility('hidden')
  },
});
Parameters:
​
visibility
string
default:"'visible'"
Visibility value (‘visible’ or ‘hidden’)
Returns: boolean Command success status

​
setFieldAnnotationsHighlighted

Set highlighted status for annotations matching predicate 
// Highlight specific field IDs
editor.commands.setFieldAnnotationsHighlighted((node) => {
  const targetIds = ['field-1', 'field-2', 'field-3'];
  return targetIds.includes(node.attrs.fieldId);
}, true)

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Highlight specific field IDs
    editor.commands.setFieldAnnotationsHighlighted((node) => {
      const targetIds = ['field-1', 'field-2', 'field-3'];
      return targetIds.includes(node.attrs.fieldId);
    }, true)
  },
});

// Remove highlighting from all annotations
editor.commands.setFieldAnnotationsHighlighted(() => true, false)

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Remove highlighting from all annotations
    editor.commands.setFieldAnnotationsHighlighted(() => true, false)
  },
});
Parameters:
​
predicate
function
Function to test each annotation node
​
highlighted
boolean
default:"true"
Whether to highlight matching annotations
Returns: boolean Command success status

​
toggleFieldAnnotationsFormat

Toggle formatting for field annotations in selection 
// Toggle bold formatting on selected annotations
editor.commands.toggleFieldAnnotationsFormat('bold');

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Toggle bold formatting on selected annotations
    editor.commands.toggleFieldAnnotationsFormat('bold');
  },
});

// Toggle italic and update selection
editor.commands.toggleFieldAnnotationsFormat('italic', true);

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Toggle italic and update selection
    editor.commands.toggleFieldAnnotationsFormat('italic', true);
  },
});
Parameters:
​
name
string
required
Format name (bold, italic, underline)
​
setSelection
boolean
Whether to set selection after toggle
Returns: boolean Command success status

​
setFieldAnnotationsFontFamily

Set font family for field annotations in current selection 
editor.commands.setFieldAnnotationsFontFamily('Arial', true)

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    editor.commands.setFieldAnnotationsFontFamily('Arial', true)
  },
});
Parameters:
​
fontFamily
string
required
Font family name to apply
​
setSelection
boolean
Whether to set node selection after update
Returns: boolean Command success status

​
setFieldAnnotationsFontSize

Set font size for field annotations in current selection 
editor.commands.setFieldAnnotationsFontSize('14pt')

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    editor.commands.setFieldAnnotationsFontSize('14pt')
  },
});
Parameters:
​
fontSize
string
required
Font size value (e.g., ‘12pt’, ‘14px’)
​
setSelection
boolean
Whether to set node selection after update
Returns: boolean Command success status

​
setFieldAnnotationsTextHighlight

Set text highlight color for field annotations in current selection 
editor.commands.setFieldAnnotationsTextHighlight('#ffff00')

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    editor.commands.setFieldAnnotationsTextHighlight('#ffff00')
  },
});
Parameters:
​
color
string
required
Highlight color value (e.g., ‘#ffff00’, ‘yellow’)
​
setSelection
boolean
Whether to set node selection after update
Returns: boolean Command success status

​
setFieldAnnotationsTextColor

Set text color for field annotations in current selection 
editor.commands.setFieldAnnotationsTextColor('#0066cc')

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    editor.commands.setFieldAnnotationsTextColor('#0066cc')
  },
});
Parameters:
​
color
string
required
Text color value (e.g., ‘#000000’, ‘black’)
​
setSelection
boolean
Whether to set node selection after update
Returns: boolean Command success status

​
Helpers

​
transactionDeletedAnything

Check if a transaction contains any deletion operations Parameters:
​
tr
Transaction
required
ProseMirror transaction to check
Returns: boolean True if transaction contains deletions

​
trackFieldAnnotationsDeletion

Track field annotation deletions in a transaction and emit events
Added in v0.11.2
// Listen for field deletions
editor.on('fieldAnnotationDeleted', ({ removedNodes }) => {
  removedNodes.forEach(({ node }) => {
    console.log(`Field ${node.attrs.fieldId} was deleted`);
    // Clean up external references
    removeFieldFromDatabase(node.attrs.fieldId);
  });
});

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: (superdoc) => {
    const editor = superdoc.activeEditor;
    // Listen for field deletions
    editor.on('fieldAnnotationDeleted', ({ removedNodes }) => {
      removedNodes.forEach(({ node }) => {
        console.log(`Field ${node.attrs.fieldId} was deleted`);
        // Clean up external references
        removeFieldFromDatabase(node.attrs.fieldId);
      });
    });
  },
});
Parameters:
​
editor
Editor
required
SuperDoc editor instance
​
tr
Transaction
required
ProseMirror transaction
Returns: void

​
handleDropOutside

Handle field annotation drops outside editor boundaries Parameters:
​
params
object
required
Drop handling parameters

​
Events

​
fieldAnnotationClicked

Field annotation clicked event Event Data:
  • node (Node) - The clicked annotation node
  • nodePos (number) - Position of the node in the document

​
fieldAnnotationDropped

Field annotation dropped event Event Data:
  • sourceField (object) - The dropped field attributes