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)
Enable users to create new fields on the fly
Field insertion menu configuration component
React.ComponentType<MenuProps>
Custom menu component
Pattern that opens the field menu
Field list sidebar configuration component
React.ComponentType<ListProps>
Custom list component
position
'left' | 'right'
default: "'right'"
Sidebar position
toolbar
boolean | string | object
Document editing toolbar. Can be: - boolean - show/hide default toolbar -
string - space-separated tool names - object - full toolbar configuration
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)
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 mode ?: "inline" | "block" ; // Field insertion mode (default: "inline") group ?: string ; // Category/group name }
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 related fields }
TriggerEvent Information about trigger detection:
interface TriggerEvent { query : string ; // Text after trigger pattern position : { // Cursor position top : number ; left : number ; }; mode : "inline" | "block" ; // Context mode }
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 MenuProps { fields : FieldDefinition []; // Available fields onInsert : ( field : FieldDefinition ) => void ; // Insert handler onClose : () => void ; // Close menu handler position : { top : number ; left : number }; // Menu position query : string ; // Current search query mode : "inline" | "block" ; // Insertion mode }
ListProps Props passed to custom list components:
interface ListProps { fields : TemplateField []; // Fields in template selectedField : TemplateField | null ; // Currently selected field onFieldSelect : ( field : TemplateField ) => void ; // Selection handler onFieldDelete : ( fieldId : string | number ) => void ; // Delete handler }
ExportConfig Configuration for template export:
interface ExportConfig { fileName ?: string ; // Download filename triggerDownload ?: boolean ; // Auto-download file }
Ref methods Access these methods via a ref:
const builderRef = useRef < SuperDocTemplateBuilderHandle >( null );
insertField() Insert a field at the current cursor position:
builderRef . current ?. insertField ({ alias: "customer_name" , mode: "inline" , });
Returns boolean - true if inserted successfully.
insertBlockField() Insert a block-level field:
builderRef . current ?. insertBlockField ({ alias: "terms_section" , mode: "block" , });
Returns boolean - true if inserted successfully.
updateField() Update an existing field:
builderRef . current ?. updateField ( "field-id" , { alias: "new_name" , tag: JSON . stringify ({ groupId: "123" }), });
Returns boolean - true if updated successfully.
deleteField() Remove a field from the template:
builderRef . current ?. deleteField ( "field-id" );
Returns boolean - true if deleted successfully.
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.docx" , triggerDownload: true , }); // Get Blob without downloading const blob = await builderRef . current ?. exportTemplate ({ triggerDownload: false , }); // Use blob for API upload or database storage await uploadToServer ( blob );
Returns Promise<void | Blob> depending on triggerDownload setting.
getSuperDoc() Access the underlying SuperDoc editor instance:
const superdoc = builderRef . current ?. getSuperDoc (); // Use SuperDoc API directly if ( superdoc ) { const editor = superdoc . getEditor (); // Full access to SuperDoc/SuperEditor APIs }
Returns SuperDoc | null.
Default components The package exports default UI components you can use as a starting point:
import { DefaultFieldMenu , DefaultFieldList , } from "@superdoc-dev/template-builder/defaults" ; // Use as-is or extend function MyCustomMenu ( props : MenuProps ) { return ( < div > < DefaultFieldMenu { ... props } /> < button onClick = {props. onClose } > Cancel </ button > </ div > ); }
CSS classes Target these classes for custom styling:
Class Element .superdoc-template-builderRoot container .superdoc-field-menuField insertion popup .superdoc-field-menu-itemIndividual menu item .superdoc-field-listSidebar container .superdoc-field-list-itemIndividual field in list .superdoc-field-list-groupGrouped fields container .superdoc-field-tagField in document .superdoc-field-tag--selectedSelected field .superdoc-field-tag--inlineInline field mode .superdoc-field-tag--blockBlock field mode
Import types All TypeScript types are exported for use in your code:
import type { SuperDocTemplateBuilderProps , SuperDocTemplateBuilderHandle , FieldDefinition , TemplateField , TriggerEvent , ExportEvent , MenuProps , ListProps , ExportConfig , } from "@superdoc-dev/template-builder" ;
Keyboard shortcuts Built-in keyboard navigation:
Shortcut Action TabJump to next field Shift + TabJump to previous field {{ (default)Open field menu EscClose field menu EnterInsert selected field from menu ↑ / ↓Navigate menu items
The trigger pattern is configurable via the menu.trigger prop. 
