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 toolbarstring - space-separated tool namesobject - 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)
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 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 } 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 , 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. 
