> ## Documentation Index
> Fetch the complete documentation index at: https://superdoc-nick-sd-2070-add-content-controls-namespace-to-doc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

Complete technical reference for the Template Builder component.

## Component props

### Required props

None - the component works with zero configuration.

### Optional props

<ParamField path="document" type="object">
  Document loading configuration

  <Expandable title="properties">
    <ParamField path="source" type="string | File | Blob">
      Document to load. Can be a URL, File object, or Blob
    </ParamField>

    <ParamField path="mode" type="'editing' | 'viewing'" default="'editing'">
      Document interaction mode
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="fields" type="object">
  Field configuration

  <Expandable title="properties">
    <ParamField path="available" type="FieldDefinition[]">
      Fields that users can insert into the template
    </ParamField>

    <ParamField path="initial" type="TemplateField[]">
      Pre-existing fields in the document (auto-discovered if not provided)
    </ParamField>

    <ParamField path="allowCreate" type="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.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="menu" type="object">
  Field insertion menu configuration

  <Expandable title="properties">
    <ParamField path="component" type="React.ComponentType<FieldMenuProps>">
      Custom menu component
    </ParamField>

    <ParamField path="trigger" type="string" default="'{{'">
      Pattern that opens the field menu
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="list" type="object">
  Field list sidebar configuration

  <Expandable title="properties">
    <ParamField path="component" type="React.ComponentType<FieldListProps>">
      Custom list component
    </ParamField>

    <ParamField path="position" type="'left' | 'right'">
      Sidebar position. Omit to hide the sidebar entirely.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="toolbar" type="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)
</ParamField>

<ParamField path="cspNonce" type="string">
  Content Security Policy nonce for dynamically injected styles
</ParamField>

<ParamField path="className" type="string">
  CSS class name for the root container
</ParamField>

<ParamField path="style" type="React.CSSProperties">
  Inline styles for the root container
</ParamField>

<ParamField path="documentHeight" type="string" default="'600px'">
  Height of the document editor area
</ParamField>

<ParamField path="telemetry" type="object">
  Telemetry configuration. Enabled by default with `source: 'template-builder'` metadata. See [Telemetry](/resources/telemetry) for details.

  <Expandable title="properties">
    <ParamField path="enabled" type="boolean" default="true">
      Enable or disable telemetry
    </ParamField>

    <ParamField path="metadata" type="Record<string, any>">
      Custom metadata merged with the default `{ source: 'template-builder' }`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="licenseKey" type="string">
  License key for SuperDoc. Passed directly to the underlying SuperDoc instance.
</ParamField>

<ParamField path="onReady" type="() => void">
  Called when the document is loaded and ready
</ParamField>

<ParamField path="onTrigger" type="(event: TriggerEvent) => void">
  Called when the trigger pattern is typed
</ParamField>

<ParamField path="onFieldInsert" type="(field: TemplateField) => void">
  Called when a field is inserted
</ParamField>

<ParamField path="onFieldUpdate" type="(field: TemplateField) => void">
  Called when a field is modified
</ParamField>

<ParamField path="onFieldDelete" type="(fieldId: string | number) => void">
  Called when a field is removed
</ParamField>

<ParamField path="onFieldsChange" type="(fields: TemplateField[]) => void">
  Called whenever the complete field list changes
</ParamField>

<ParamField path="onFieldSelect" type="(field: TemplateField | null) => void">
  Called when a field is selected/deselected in the document
</ParamField>

<ParamField path="onFieldCreate" type="(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.
</ParamField>

<ParamField path="onExport" type="(event: ExportEvent) => void">
  Called when template is exported via `exportTemplate()`. Use this to persist field metadata to your database alongside the document.

  <Expandable title="ExportEvent properties">
    <ParamField path="fields" type="TemplateField[]">
      All fields in the exported template
    </ParamField>

    <ParamField path="blob" type="Blob | undefined">
      The exported document (only present when `triggerDownload: false`)
    </ParamField>

    <ParamField path="fileName" type="string">
      The filename used for export
    </ParamField>
  </Expandable>
</ParamField>

## Types

### FieldDefinition

Available fields that users can insert:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
interface ExportConfig {
  fileName?: string;         // Download filename (default: "document")
  triggerDownload?: boolean;  // Auto-download file (default: true)
}
```

## Ref methods

Access these methods via a ref:

```typescript theme={null}
const builderRef = useRef<SuperDocTemplateBuilderHandle>(null);
```

### insertField()

Insert an inline field at the current cursor position:

```typescript theme={null}
builderRef.current?.insertField({
  alias: "customer_name",
  fieldType: "owner",
});
```

Returns `boolean` - true if inserted successfully.

### insertBlockField()

Insert a block-level field:

```typescript theme={null}
builderRef.current?.insertBlockField({
  alias: "signature",
  fieldType: "signer",
});
```

Returns `boolean` - true if inserted successfully.

### updateField()

Update an existing field:

```typescript theme={null}
builderRef.current?.updateField("field-id", {
  alias: "new_name",
});
```

Returns `boolean` - true if updated successfully.

### deleteField()

Remove a field from the template:

```typescript theme={null}
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:

```typescript theme={null}
builderRef.current?.selectField("field-id");
```

### nextField()

Navigate to the next field (equivalent to Tab key):

```typescript theme={null}
builderRef.current?.nextField();
```

### previousField()

Navigate to the previous field (equivalent to Shift+Tab):

```typescript theme={null}
builderRef.current?.previousField();
```

### getFields()

Get all fields in the template:

```typescript theme={null}
const fields = builderRef.current?.getFields();
// Returns: TemplateField[]
```

### exportTemplate()

Export the template as a .docx file:

```typescript theme={null}
// 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:

```typescript theme={null}
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:

```jsx theme={null}
import "@superdoc-dev/template-builder/field-types.css";
```

Override colors with CSS variables:

```css theme={null}
: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:

```typescript theme={null}
import type {
  SuperDocTemplateBuilderProps,
  SuperDocTemplateBuilderHandle,
  FieldDefinition,
  TemplateField,
  TriggerEvent,
  ExportEvent,
  ExportConfig,
  FieldMenuProps,
  FieldListProps,
  ToolbarConfig,
  DocumentConfig,
  FieldsConfig,
  MenuConfig,
  ListConfig,
} from "@superdoc-dev/template-builder";
```