Field Annotation

Interactive form fields for documents. It can be used when variable content is needed inside the document. Supports text, signature, image, checkbox, link, and HTML field types.

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:

Usage

// 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

Find & Search

findFieldAnnotations

Find field annotations matching a predicate function

Added in v0.10.3

Usage

// 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
    );
  },
});

Usage

// 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

Show Object properties

pos · number · required

pos of each object

node · Node · required

node of each object

findFieldAnnotationsBetween

Find all field annotations between two positions

Usage

// 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);
  },
});

Usage

// 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

Show Object properties

pos · number · required

pos of each object

node · Node · required

node of each object

findFieldAnnotationsByFieldId

Find field annotations by field ID(s)

Usage

// 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);
  },
});

Usage

// 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

Show Object properties

pos · number · required

pos of each object

node · Node · required

node of each object

findFirstFieldAnnotationByFieldId

Find the first field annotation matching a field ID

Added in v0.10.2

Usage

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

Usage

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

Show Object properties

node · Node · required

node of each object

pos · number · required

pos of each object

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

Show Object properties

pos · number · required

pos of each object

node · Node · required

node of each object

getAllFieldAnnotationsWithRect

Get all field annotations with their bounding rectangles

Added in v0.11.0

Usage

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

Show Object properties

pos · number · required

pos of each object

node · Node · required

node of each object

rect · DOMRect · required

rect of each object

Delete & Remove

findRemovedFieldAnnotations

Find field annotation nodes that were removed in a transaction

Added in v0.11.2

Usage

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

Show Object properties

node · Node · required

node of each object

pos · number · required

pos of each object

deleteFieldAnnotations

Delete field annotations by field ID

Usage

// 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')
  },
});

Usage

// 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

Usage

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

Usage

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

Usage

// 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)
  },
});

Usage

// 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

Usage

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

Hide properties

fieldId · string · required

Unique field identifier

displayLabel · string · required

Text to display in annotation

fieldType · string

Type of field (TEXTINPUT, CHECKBOX, etc.)

fieldColor · string

Background color for annotation

type · string · default: "'text'"

Annotation type (text, image, signature, etc.)

editorFocus · boolean

Whether to focus editor after insertion

Returns: boolean Command success status

addFieldAnnotationAtSelection

Add field annotation at current selection position

Usage

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

Usage

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

Hide properties

from · number · required

Start position

to · number · required

End position

attrs · Object · required

Field annotation attributes

Returns: boolean Command success status

replaceFieldAnnotationsWithLabelInSelection

Replace field annotations with text labels in current selection

Added in v0.11.0

Usage

// 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

Usage

// 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'])
  },
});

Usage

// 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

Hide properties

isInSelection · boolean

Replace only in selection

addToHistory · boolean

Add operation to undo history

types · Array.<string>

Annotation types to replace

Returns: boolean Command success status

resetFieldAnnotations

Reset all field annotations to their default values

Usage

// 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

Usage

// 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'
    })
  },
});

Usage

// 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

Hide properties

displayLabel · string

New display label

fieldColor · string

New field color

hidden · boolean

Hide/show annotation

Returns: boolean Command success status

updateFieldAnnotation

Update a specific field annotation instance

Usage

// 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

Usage

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

Usage

// 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);
    })
  },
});

Usage

// 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

Usage

// 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

Usage

// 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')
  },
});

Usage

// 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

Usage

// 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)
  },
});

Usage

// 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

Usage

// 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');
  },
});

Usage

// 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

Usage

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

Usage

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

Usage

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

Usage

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

Usage

// 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

Hide properties

fieldAnnotation · string · required

Serialized field data

editor · object · required

SuperDoc editor instance

view · object · required

ProseMirror editor view

event · object · required

Browser drag event

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