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.

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.

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";

Getting Started

Editor

Document Engine

AI

Solutions

Resources

Component props

Required props

Optional props

Types

FieldDefinition

TemplateField

TriggerEvent

ExportEvent

FieldMenuProps

FieldListProps

ExportConfig

Ref methods

insertField()

insertBlockField()

updateField()

deleteField()

selectField()

nextField()

previousField()

getFields()

refresh()

exportTemplate()

getSuperDoc()

Field type styling

CSS classes

Import types

​Component props

​Required props

​Optional props

​Types

​FieldDefinition

​TemplateField

​TriggerEvent

​ExportEvent

​FieldMenuProps

​FieldListProps

​ExportConfig

​Ref methods

​insertField()

​insertBlockField()

​updateField()

​deleteField()

​selectField()

​nextField()

​previousField()

​getFields()

​refresh()

​exportTemplate()

​getSuperDoc()

​Field type styling

​CSS classes

​Import types

Component props

Required props

Optional props

Types

FieldDefinition

TemplateField

TriggerEvent

ExportEvent

FieldMenuProps

FieldListProps

ExportConfig

Ref methods

insertField()

insertBlockField()

updateField()

deleteField()

selectField()

nextField()

previousField()

getFields()

refresh()

exportTemplate()

getSuperDoc()

Field type styling

CSS classes

Import types