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.

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;
}

Add the field list sidebar

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