Quick Start Guide

Get your template builder up and running in 5 minutes.

Installation

npm install @superdoc-dev/template-builder

Basic usage

Import the component and styles, then render with minimal props:

import SuperDocTemplateBuilder from "@superdoc-dev/template-builder";
import "superdoc/style.css";

function App() {
  return (
    <SuperDocTemplateBuilder
      fields={{
        available: [
          { id: "1", label: "Customer Name" },
          { id: "2", label: "Contract Date" },
        ],
      }}
    />
  );
}

That displays an empty document. Type {{ to open the field menu and insert fields.

Load an existing document

Most templates start from an existing document:

<SuperDocTemplateBuilder
  document={{
    source: "my-template.docx",
    mode: "editing",
  }}
  fields={{
    available: [
      { id: "1", label: "Customer Name" },
      { id: "2", label: "Invoice Date" },
      { id: "3", label: "Amount Due" },
    ],
  }}
/>

The component loads the document and discovers any existing fields.

Add field types

Distinguish between owner-filled and signer-filled fields:

<SuperDocTemplateBuilder
  fields={{
    available: [
      { id: "1", label: "Company Name", fieldType: "owner" },
      { id: "2", label: "Signer Name", fieldType: "signer" },
      { id: "3", label: "Signature", mode: "block", fieldType: "signer" },
    ],
  }}
/>

Fields default to 'owner' when no fieldType is specified.

Add preset block content

If a field should insert a predefined structure (for example, a table), add presetContent on a block field:

<SuperDocTemplateBuilder
  fields={{
    available: [
      {
        id: "sample_table",
        label: "Sample Table",
        mode: "block",
        fieldType: "data",
        presetContent: {
          html: "<table style=\"border-collapse: collapse; width: 100%;\"><tr><th style=\"border: 1px solid #000;\">Column A</th><th style=\"border: 1px solid #000;\">Column B</th></tr><tr><td style=\"border: 1px solid #000;\"></td><td style=\"border: 1px solid #000;\"></td></tr></table>",
        },
      },
    ],
  }}
/>

presetContent applies only to block fields. Inline fields ignore it.

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.

Color-code fields in the editor

Import the optional CSS to visually distinguish field types:

import "@superdoc-dev/template-builder/field-types.css";

Customize colors with CSS variables:

:root {
  --superdoc-field-owner-color: #629be7;
  --superdoc-field-signer-color: #d97706;
}

Show all template fields in a sidebar:

<SuperDocTemplateBuilder
  document={{ source: "template.docx", mode: "editing" }}
  fields={{
    available: [
      { id: "1", label: "Customer Name" },
      { id: "2", label: "Invoice Date" },
    ],
  }}
  list={{ position: "right" }}
/>

Users can click fields in the list to jump to them in the document.

Handle field changes

Track when fields are inserted, updated, or deleted:

function App() {
  const [templateFields, setTemplateFields] = useState([]);

  return (
    <SuperDocTemplateBuilder
      document={{ source: "template.docx", mode: "editing" }}
      fields={{ available: myFields }}
      list={{ position: "right" }}
      onFieldsChange={(fields) => {
        console.log("Template now has", fields.length, "fields");
        setTemplateFields(fields);
      }}
    />
  );
}

The onFieldsChange callback receives the complete list of fields in the template whenever they change. Each field includes its fieldType.

Export the template

Use a ref to programmatically export:

import { useRef } from "react";

function App() {
  const builderRef = useRef(null);

  const handleExport = async () => {
    await builderRef.current?.exportTemplate({
      fileName: "my-template",
      triggerDownload: true,
    });
  };

  return (
    <>
      <button onClick={handleExport}>Export Template</button>
      <SuperDocTemplateBuilder
        ref={builderRef}
        document={{ source: "template.docx", mode: "editing" }}
        fields={{ available: myFields }}
        list={{ position: "right" }}
        onExport={(event) => {
          console.log("Exported", event.fields.length, "fields");
        }}
      />
    </>
  );
}

The exported document contains all field definitions embedded as Structured Document Tags.

TypeScript support

Full TypeScript definitions are included:

import SuperDocTemplateBuilder from "@superdoc-dev/template-builder";
import type {
  SuperDocTemplateBuilderHandle,
  FieldDefinition,
  TemplateField,
} from "@superdoc-dev/template-builder";

const builderRef = useRef<SuperDocTemplateBuilderHandle>(null);

const availableFields: FieldDefinition[] = [
  { id: "1", label: "Customer Name", defaultValue: "John Doe" },
  { id: "2", label: "Signer Name", fieldType: "signer" },
];

const handleFieldInsert = (field: TemplateField) => {
  console.log(`Inserted: ${field.alias} (${field.fieldType})`);
};

Next steps

Configuration Options

Learn about custom components, field creation, and advanced features

Getting Started

Editor

Document Engine

AI

Solutions

Resources

Quick Start Guide

Installation

Basic usage

Load an existing document

Add field types

Add preset block content

Color-code fields in the editor

Add the field list sidebar

Handle field changes

Export the template

TypeScript support

Next steps

Configuration Options

​Installation

​Basic usage

​Load an existing document

​Add field types

​Add preset block content

​Color-code fields in the editor

​Add the field list sidebar

​Handle field changes

​Export the template

​TypeScript support

​Next steps

Configuration Options

Installation

Basic usage

Load an existing document

Add field types

Add preset block content

Color-code fields in the editor

Add the field list sidebar

Handle field changes

Export the template

TypeScript support

Next steps