> ## Documentation Index
> Fetch the complete documentation index at: https://superdoc-caio-pizzol-docs-ai-core-preset.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. Reactive: changing this at runtime switches modes without recreating the editor.
    </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="defaultLockMode" type="'unlocked' | 'sdtLocked' | 'contentLocked' | 'sdtContentLocked'">
  Lock mode for all inserted fields. Per-field `lockMode` overrides this. See [lock modes](/extensions/structured-content#lock-modes).
</ParamField>

<ParamField path="fieldColors" type="Record<string, string>">
  Colors for field types in the document and sidebar. Keys are `fieldType` values, values are CSS colors (e.g. `{ owner: '#629be7', signer: '#d97706' }`). Generates scoped CSS automatically: no stylesheet import needed.
</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
  presetContent?: {
    html?: string;                 // Block preset as HTML
    json?: unknown;                // Block preset as ProseMirror JSON
  };
  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")
  lockMode?: LockMode;             // Lock mode for this field (overrides defaultLockMode)
}
```

`presetContent` is applied only for `mode: "block"` fields. Inline fields ignore it.

### 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"
  lockMode?: LockMode;       // Current lock mode of this field
}
```

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

### refresh()

Re-discover fields from the editor and trigger `onFieldsChange`. Use this when field data arrives asynchronously or after external changes to the document:

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

### 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

Use the `fieldColors` prop to color-code fields by type:

```tsx theme={null}
<SuperDocTemplateBuilder
  fieldColors={{
    owner: "#629be7",
    signer: "#d97706",
    date: "#059669",
  }}
/>
```

This generates scoped CSS automatically. Each color controls the field border and label in the document. Sidebar badges match.

For manual control, you can still import the standalone stylesheet and use CSS variables:

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

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