Complete technical reference for the Template Builder component.
Component props Required props None - the component works with zero configuration.
Optional props Document loading configuration Document to load. Can be a URL, File object, or Blob
mode
'editing' | 'viewing'
default: "'editing'"
Document interaction mode
Field configuration Fields that users can insert into the template
Pre-existing fields in the document (auto-discovered if not provided)
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 component
React.ComponentType<FieldMenuProps>
Custom menu component
Pattern that opens the field menu
Field list sidebar configuration component
React.ComponentType<FieldListProps>
Custom list component
Sidebar position. Omit to hide the sidebar entirely.
toolbar
boolean | string | ToolbarConfig
Document editing toolbar.
true — render a default toolbar containerstring — CSS selector of an existing element to mount the toolbar intoobject — full toolbar configuration (see ToolbarConfig) Content Security Policy nonce for dynamically injected styles
CSS class name for the root container
Inline styles for the root container
Height of the document editor area
Telemetry configuration. Enabled by default with source: 'template-builder' metadata. See Telemetry for details. Enable or disable telemetry
Custom metadata merged with the default { source: 'template-builder' }
License key for SuperDoc. Passed directly to the underlying SuperDoc instance.
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
All fields in the exported template
The exported document (only present when triggerDownload: false)
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 }
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-builderRoot container .superdoc-template-builder-sidebarSidebar wrapper .superdoc-template-builder-documentDocument area wrapper .superdoc-template-builder-editorEditor container .superdoc-template-builder-toolbarDefault toolbar container .superdoc-field-menuField insertion popup .superdoc-field-listSidebar 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" ;
