Field Annotation - SuperDoc

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

Find & Search

`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

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

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

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)

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

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

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

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

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

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:

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

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

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

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

Hide properties

from

number

required

Start position

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

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

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

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

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

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

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

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

​Configuration

​Usage

​Commands

​Find & Search

​findFieldAnnotations

​findFieldAnnotationsBetween

​findFieldAnnotationsByFieldId

​findFirstFieldAnnotationByFieldId

​findHeaderFooterAnnotationsByFieldId

​getAllFieldAnnotations

​getAllFieldAnnotationsWithRect

​Delete & Remove

​findRemovedFieldAnnotations

​deleteFieldAnnotations

​deleteFieldAnnotationsByNode

​deleteFieldAnnotation

​sliceFieldAnnotations

​Create & Add

​addFieldAnnotation

​addFieldAnnotationAtSelection

​Update & Edit

​replaceWithFieldAnnotation

​replaceFieldAnnotationsWithLabelInSelection

​replaceFieldAnnotationsWithLabel

​resetFieldAnnotations

​updateFieldAnnotations

​updateFieldAnnotation

​updateFieldAnnotationsAttributes

​setFieldAnnotationsHiddenByCondition

​unsetFieldAnnotationsHidden

​setFieldAnnotationsVisibility

​setFieldAnnotationsHighlighted

​toggleFieldAnnotationsFormat

​setFieldAnnotationsFontFamily

​setFieldAnnotationsFontSize

​setFieldAnnotationsTextHighlight

​setFieldAnnotationsTextColor

​Helpers

​transactionDeletedAnything

​trackFieldAnnotationsDeletion

​handleDropOutside

​Events

​fieldAnnotationClicked

​fieldAnnotationDropped

Configuration

Usage

Commands

Find & Search

`findFieldAnnotations`

`findFieldAnnotationsBetween`

`findFieldAnnotationsByFieldId`

`findFirstFieldAnnotationByFieldId`

`findHeaderFooterAnnotationsByFieldId`

`getAllFieldAnnotations`

`getAllFieldAnnotationsWithRect`

Delete & Remove

`findRemovedFieldAnnotations`

`deleteFieldAnnotations`

`deleteFieldAnnotationsByNode`

`deleteFieldAnnotation`

`sliceFieldAnnotations`

Create & Add

`addFieldAnnotation`

`addFieldAnnotationAtSelection`

Update & Edit

`replaceWithFieldAnnotation`

`replaceFieldAnnotationsWithLabelInSelection`

`replaceFieldAnnotationsWithLabel`

`resetFieldAnnotations`

`updateFieldAnnotations`

`updateFieldAnnotation`

`updateFieldAnnotationsAttributes`

`setFieldAnnotationsHiddenByCondition`

`unsetFieldAnnotationsHidden`

`setFieldAnnotationsVisibility`

`setFieldAnnotationsHighlighted`

`toggleFieldAnnotationsFormat`

`setFieldAnnotationsFontFamily`

`setFieldAnnotationsFontSize`

`setFieldAnnotationsTextHighlight`

`setFieldAnnotationsTextColor`

Helpers

`transactionDeletedAnything`

`trackFieldAnnotationsDeletion`

`handleDropOutside`

Events

`fieldAnnotationClicked`

`fieldAnnotationDropped`