API Reference

Complete technical reference for the Template Builder component.

Component props

Required props

None - the component works with zero configuration.

Optional props

document · object

Document loading configuration

Show properties

source · string | File | Blob

Document to load. Can be a URL, File object, or Blob

mode · 'editing' | 'viewing' · default: "'editing'"

Document interaction mode. Reactive: changing this at runtime switches modes without recreating the editor.

fields · object

Field configuration

Show properties

available · FieldDefinition[]

Fields that users can insert into the template

initial · TemplateField[]

Pre-existing fields in the document (auto-discovered if not provided)

allowCreate · boolean · default: "false"

Show a “Create New Field” option in the menu. The create form lets users pick inline/block mode and owner/signer field type.

menu · object

Field insertion menu configuration

Show properties

component · React.ComponentType<FieldMenuProps>

Custom menu component

trigger · string · default: "'{{'"

Pattern that opens the field menu

list · object

Field list sidebar configuration

Show properties

component · React.ComponentType<FieldListProps>

Custom list component

position · 'left' | 'right'

Sidebar position. Omit to hide the sidebar entirely.

toolbar · boolean | string | ToolbarConfig

Document editing toolbar.

• true: render a default toolbar container
• string: CSS selector of an existing element to mount the toolbar into
• object: full toolbar configuration (see ToolbarConfig)

defaultLockMode · 'unlocked' | 'sdtLocked' | 'contentLocked' | 'sdtContentLocked'

Lock mode for all inserted fields. Per-field lockMode overrides this. See lock modes.

fieldColors · Record<string, string>

Colors for field types in the document and sidebar. Keys are fieldType values, values are CSS colors (e.g. { owner: '#629be7', signer: '#d97706' }). Generates scoped CSS automatically: no stylesheet import needed.

cspNonce · string

Content Security Policy nonce for dynamically injected styles

className · string

CSS class name for the root container

style · React.CSSProperties

Inline styles for the root container

documentHeight · string · default: "'600px'"

Height of the document editor area

telemetry · object

Telemetry configuration. Enabled by default with source: 'template-builder' metadata. See Telemetry for details.

Show properties

enabled · boolean · default: "true"

Enable or disable telemetry

metadata · Record<string, any>

Custom metadata merged with the default { source: 'template-builder' }

licenseKey · string

License key for SuperDoc. Passed directly to the underlying SuperDoc instance.

onReady · () => void

Called when the document is loaded and ready

onTrigger · (event: TriggerEvent) => void

Called when the trigger pattern is typed

onFieldInsert · (field: TemplateField) => void

Called when a field is inserted

onFieldUpdate · (field: TemplateField) => void

Called when a field is modified

onFieldDelete · (fieldId: string | number) => void

Called when a field is removed

onFieldsChange · (fields: TemplateField[]) => void

Called whenever the complete field list changes

onFieldSelect · (field: TemplateField | null) => void

Called when a field is selected/deselected in the document

onFieldCreate · (field: FieldDefinition) => void | Promise<FieldDefinition | void>

Called when user creates a new field (requires fields.allowCreate = true). Return a modified FieldDefinition to override the field before insertion, or void to use the field as-is.

onExport · (event: ExportEvent) => void

Called when template is exported via exportTemplate(). Use this to persist field metadata to your database alongside the document.

Show ExportEvent properties

fields · TemplateField[]

All fields in the exported template

blob · Blob | undefined

The exported document (only present when triggerDownload: false)

fileName · string

The filename used for export

Types

FieldDefinition

Available fields that users can insert:

interface FieldDefinition {
  id: string;                      // Unique identifier
  label: string;                   // Display name
  defaultValue?: string;           // Default value for new instances
  presetContent?: {
    html?: string;                 // Block preset as HTML
    json?: unknown;                // Block preset as ProseMirror JSON
  };
  metadata?: Record<string, any>;  // Custom metadata stored in the SDT tag
  mode?: "inline" | "block";       // Insertion mode (default: "inline")
  group?: string;                  // Group ID for linked fields
  fieldType?: string;              // Field type, e.g. "owner" or "signer" (default: "owner")
  lockMode?: LockMode;             // Lock mode for this field (overrides defaultLockMode)
}

presetContent is applied only for mode: "block" fields. Inline fields ignore it.

TemplateField

Fields that exist in the template document:

interface TemplateField {
  id: string | number;       // Unique instance ID
  alias: string;             // Field name/label
  tag?: string;              // JSON metadata string
  position?: number;         // Position in document
  mode?: "inline" | "block"; // Rendering mode
  group?: string;            // Group ID for linked fields
  fieldType?: string;        // Field type, e.g. "owner" or "signer"
  lockMode?: LockMode;       // Current lock mode of this field
}

TriggerEvent

Information about trigger detection:

interface TriggerEvent {
  position: { from: number; to: number }; // Document position of the trigger
  bounds?: DOMRect;                        // Viewport coordinates for menu positioning
  cleanup: () => void;                     // Removes the trigger text from the document
}

ExportEvent

Data provided when a template is exported:

interface ExportEvent {
  fields: TemplateField[]; // All fields in the template
  blob?: Blob;             // Document blob (when triggerDownload: false)
  fileName: string;        // Export filename
}

FieldMenuProps

Props passed to custom menu components:

interface FieldMenuProps {
  isVisible: boolean;                      // Whether the menu should be shown
  position?: DOMRect;                      // Viewport coordinates for positioning
  availableFields: FieldDefinition[];      // All available fields
  filteredFields?: FieldDefinition[];      // Fields filtered by the typed query
  filterQuery?: string;                    // Text typed after the trigger pattern
  allowCreate?: boolean;                   // Whether "Create New Field" is enabled
  existingFields?: TemplateField[];        // Fields already in the document
  onSelect: (field: FieldDefinition) => void;        // Insert a new field
  onSelectExisting?: (field: TemplateField) => void;  // Insert a linked copy
  onClose: () => void;                     // Close the menu
  onCreateField?: (field: FieldDefinition) => void | Promise<FieldDefinition | void>;
}

FieldListProps

Props passed to custom list components:

interface FieldListProps {
  fields: TemplateField[];                          // Fields in the template
  onSelect: (field: TemplateField) => void;         // Select/navigate to a field
  onDelete: (fieldId: string | number) => void;     // Delete a field
  onUpdate?: (field: TemplateField) => void;        // Update a field
  selectedFieldId?: string | number;                // Currently selected field ID
}

ExportConfig

Configuration for template export:

interface ExportConfig {
  fileName?: string;         // Download filename (default: "document")
  triggerDownload?: boolean;  // Auto-download file (default: true)
}

Ref methods

Access these methods via a ref:

const builderRef = useRef<SuperDocTemplateBuilderHandle>(null);

insertField()

Insert an inline field at the current cursor position:

builderRef.current?.insertField({
  alias: "customer_name",
  fieldType: "owner",
});

Returns boolean - true if inserted successfully.

insertBlockField()

Insert a block-level field:

builderRef.current?.insertBlockField({
  alias: "signature",
  fieldType: "signer",
});

Returns boolean - true if inserted successfully.

updateField()

Update an existing field:

builderRef.current?.updateField("field-id", {
  alias: "new_name",
});

Returns boolean - true if updated successfully.

deleteField()

Remove a field from the template:

builderRef.current?.deleteField("field-id");

Returns boolean - true if deleted successfully. If the deleted field was the last in a group with two members, the remaining field’s group tag is automatically removed.

selectField()

Programmatically select a field:

builderRef.current?.selectField("field-id");

nextField()

Navigate to the next field (equivalent to Tab key):

builderRef.current?.nextField();

previousField()

Navigate to the previous field (equivalent to Shift+Tab):

builderRef.current?.previousField();

getFields()

Get all fields in the template:

const fields = builderRef.current?.getFields();
// Returns: TemplateField[]

refresh()

Re-discover fields from the editor and trigger onFieldsChange. Use this when field data arrives asynchronously or after external changes to the document:

builderRef.current?.refresh();

exportTemplate()

Export the template as a .docx file:

// Trigger download
await builderRef.current?.exportTemplate({
  fileName: "my-template",
  triggerDownload: true,
});

// Get Blob without downloading
const blob = await builderRef.current?.exportTemplate({
  triggerDownload: false,
});

Returns Promise<void | Blob> depending on triggerDownload setting.

getSuperDoc()

Access the underlying SuperDoc editor instance:

const superdoc = builderRef.current?.getSuperDoc();

if (superdoc?.activeEditor) {
  // Full access to SuperDoc/SuperEditor APIs
  superdoc.activeEditor.commands.search("hello");
}

Returns SuperDoc | null.

Field type styling

Use the fieldColors prop to color-code fields by type:

<SuperDocTemplateBuilder
  fieldColors={{
    owner: "#629be7",
    signer: "#d97706",
    date: "#059669",
  }}
/>

This generates scoped CSS automatically. Each color controls the field border and label in the document. Sidebar badges match.

For manual control, you can still import the standalone stylesheet and use CSS variables:

import "@superdoc-dev/template-builder/field-types.css";

:root {
  --superdoc-field-owner-color: #629be7;
  --superdoc-field-signer-color: #d97706;
}

CSS classes

Target these classes for custom styling:

Class	Element
.superdoc-template-builder	Root container
.superdoc-template-builder-sidebar	Sidebar wrapper
.superdoc-template-builder-document	Document area wrapper
.superdoc-template-builder-editor	Editor container
.superdoc-template-builder-toolbar	Default toolbar container
.superdoc-field-menu	Field insertion popup
.superdoc-field-list	Sidebar field list

Import types

All TypeScript types are exported:

import type {
  SuperDocTemplateBuilderProps,
  SuperDocTemplateBuilderHandle,
  FieldDefinition,
  TemplateField,
  LockMode,
  TriggerEvent,
  ExportEvent,
  ExportConfig,
  FieldMenuProps,
  FieldListProps,
  ToolbarConfig,
  DocumentConfig,
  FieldsConfig,
  MenuConfig,
  ListConfig,
} from "@superdoc-dev/template-builder";