> ## 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.
# Configuration Options
Complete guide to configuring the template builder component.
## Document options
Control which document is loaded and how users interact with it:
```tsx theme={null}
```
**Editing mode** - Users can edit document content and insert fields.
**Viewing mode** - Read-only document display, fields can still be inserted.
Changing `mode` at runtime switches between editing and viewing without recreating the editor: no scroll jump or content flash:
```tsx theme={null}
```
## Field system
### Available fields
Define which fields users can insert:
```tsx theme={null}
```
### Field types
Tag fields with a `fieldType` to distinguish roles:
```tsx theme={null}
```
Color-code fields in the document and sidebar with `fieldColors`:
```tsx theme={null}
```
Each color controls the field's border and label in the document. The sidebar badges match automatically. Custom field types beyond `owner` and `signer` work the same way: just add them to `fieldColors`.
You can also import `@superdoc-dev/template-builder/field-types.css` directly and use CSS variables instead. The `fieldColors` prop is the recommended approach: no extra imports needed.
The `fieldType` value flows through all callbacks (`onFieldInsert`, `onFieldsChange`, `onExport`, etc.) and is stored in the SDT tag metadata.
### Preset block content
Use `presetContent` to prefill block fields with a structure such as a table or list:
```tsx theme={null}
Column A
Column B
",
// or json: { ...ProseMirror JSON... }
},
},
],
}}
/>
```
`presetContent` is passed into the existing block insertion command. For `mode: "inline"` fields, `presetContent` is ignored.
* `presetContent.json` is recommended when you need the most reliable preservation of structure, semantics, and editor-compatible styling.
* With `presetContent.html`, include required attributes and inline styles explicitly so the HTML parser can map them into node attributes.
### Field creation
Allow users to create new fields while building templates:
```tsx theme={null}
{
// field.id starts with "custom_"
// field.fieldType is "owner" or "signer" (user-selected)
// field.mode is "inline" or "block" (user-selected)
const savedField = await api.createField(field);
// Return updated field or void
return { ...field, id: savedField.id };
}}
/>
```
When enabled, the field menu shows a "Create New Field" option with inputs for name, mode (inline/block), and field type (owner/signer).
### Field locking
Make fields read-only so end users can't edit their content:
```tsx theme={null}
```
Per-field `lockMode` overrides `defaultLockMode`. The default field creation form includes a "Locked" checkbox that sets `contentLocked`.
Template authors can always delete and manage fields regardless of lock mode: locking only affects end users interacting with the document. For advanced use cases, see [lock modes](/extensions/structured-content#lock-modes).
### Linked fields
When a user selects an existing field from the "Existing Fields" section in the menu, a linked copy is inserted. Both instances share a group ID and stay in sync.
The menu automatically groups existing fields and shows the count. When the last field in a group is deleted, the remaining field's group tag is removed.
## Menu customization
### Trigger pattern
Change what opens the field insertion menu:
```tsx theme={null}
```
### Custom menu component
Replace the default field menu entirely:
```tsx theme={null}
function CustomMenu({
isVisible,
position,
filteredFields,
filterQuery,
existingFields,
allowCreate,
onSelect,
onSelectExisting,
onClose,
}) {
if (!isVisible) return null;
return (
{filterQuery &&
Searching: {filterQuery}
}
{existingFields?.length > 0 && (
Existing fields
{existingFields.map((field) => (
))}
)}
Available fields
{filteredFields.map((field) => (
))}
);
}
;
```
The component handles trigger detection, filtering, and positioning. You render the UI.
## List sidebar
### Position and visibility
```tsx theme={null}
```
Omit `list` prop entirely to hide the sidebar.
### Custom list component
Replace the default sidebar:
```tsx theme={null}
function CustomFieldList({ fields, onSelect, onDelete, selectedFieldId }) {
return (
);
}
;
```
## Toolbar configuration
Control the document editing toolbar:
```tsx theme={null}
// Boolean: render default toolbar container
// String: mount into an existing element
// Object: full control
```
## Event handlers
### Field lifecycle events
```tsx theme={null}
{
console.log("Inserted:", field.alias, field.fieldType);
}}
onFieldUpdate={(field) => {
console.log("Updated:", field.alias);
}}
onFieldDelete={(fieldId) => {
console.log("Deleted:", fieldId);
}}
onFieldsChange={(fields) => {
console.log("Template has", fields.length, "fields");
const signerFields = fields.filter((f) => f.fieldType === "signer");
console.log("Signer fields:", signerFields.length);
}}
/>
```
### Selection and interaction
```tsx theme={null}
{
if (field) {
console.log("Selected:", field.alias, field.fieldType);
}
}}
onTrigger={(event) => {
console.log("Trigger at:", event.position);
console.log("Bounds:", event.bounds);
}}
/>
```
### Export event
```tsx theme={null}
{
console.log("Exported", event.fields.length, "fields");
console.log("File:", event.fileName);
// event.blob is available when triggerDownload: false
}}
/>
```
### Document ready
```tsx theme={null}
{
console.log("Document loaded and ready");
}}
/>
```
## Telemetry
Telemetry is enabled by default with `source: 'template-builder'` metadata. You can override or extend the defaults:
```tsx theme={null}
```
To disable telemetry:
```tsx theme={null}
```
For more details on how telemetry works, see the [Telemetry](/resources/telemetry) page.
### License key
Pass `licenseKey` to identify your organization in telemetry:
```tsx theme={null}
```
The key is used solely for organization identification. It does not enable or disable any features, and nothing is blocked if a usage quota is reached. The key is forwarded to the underlying SuperDoc instance.
## Complete example
Putting it all together:
```tsx theme={null}
import { useState, useRef } from "react";
import SuperDocTemplateBuilder from "@superdoc-dev/template-builder";
import type {
SuperDocTemplateBuilderHandle,
FieldDefinition,
} from "@superdoc-dev/template-builder";
import "superdoc/style.css";
import "@superdoc-dev/template-builder/field-types.css";
function TemplateEditor() {
const builderRef = useRef(null);
const [fields, setFields] = useState([
{ id: "1", label: "Customer Name" },
{ id: "2", label: "Customer Email" },
{ id: "3", label: "Invoice Date" },
{ id: "4", label: "Total Amount" },
{ id: "5", label: "Signer Name", fieldType: "signer" },
{ id: "6", label: "Signature", mode: "block", fieldType: "signer" },
]);
const handleExport = async () => {
await builderRef.current?.exportTemplate({
fileName: "invoice-template",
});
};
const handleFieldCreate = async (field: FieldDefinition) => {
const saved = await fetch("/api/fields", {
method: "POST",
body: JSON.stringify(field),
}).then((r) => r.json());
setFields((prev) => [...prev, { ...field, id: saved.id }]);
return { ...field, id: saved.id };
};
return (