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

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)

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
  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")
}

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

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[]

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

Import the optional CSS to color-code fields by type in the editor:

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

Override colors with CSS variables:

: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,
  TriggerEvent,
  ExportEvent,
  ExportConfig,
  FieldMenuProps,
  FieldListProps,
  ToolbarConfig,
  DocumentConfig,
  FieldsConfig,
  MenuConfig,
  ListConfig,
} from "@superdoc-dev/template-builder";