> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spitshake.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedding Overview

> Embed signing forms and template builders directly into your application using web components, the JavaScript SDK, or iframes.

# Embedding Overview

DocuTrust provides three approaches to embed document signing and template building directly into your application. Choose the one that best fits your architecture and level of control.

## Approaches

### 1. Web Components

Drop-in HTML custom elements that work in any web page or framework.

* **`<docuseal-form>`** renders a signing form for a specific submission.
* **`<docuseal-builder>`** renders the template editor for building and configuring document templates.

No framework dependency required. Add the script tag, drop in the element, and configure via `data-*` attributes.

```html theme={null}
<script src="https://your-app.com/js/docutrust-embed.js"></script>

<docuseal-form
  data-src="https://your-app.com/s/aB3kL9mNpQ"
  data-email="jane.doe@example.com"
  data-name="Jane Doe"
  data-role="Recipient"
  data-language="en"
  data-with-title="true"
  data-with-send-copy-button="true"
  data-with-download-button="true"
  data-allow-to-resubmit="false"
  data-go-to-last="true"
  data-autoscroll="true"
  data-expand="true"
  data-completed-redirect-url="https://your-app.com/thank-you"
  data-values='{"Full Name": "Jane Doe", "Email": "jane.doe@example.com"}'
  data-metadata='{"customer_id": "cust_8472", "plan": "enterprise"}'
></docuseal-form>

<docuseal-builder
  data-token="eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxNSIsImlzcyI6ImRvY3V0cnVzdCIsImF1ZCI6ImJ1aWxkZXIiLCJhaWQiOiIxIiwiaWF0IjoxNzQ0MTk1OTIwLCJleHAiOjE3NDQyMTAzMjAsIm9wdHMiOnsiYXV0b3NhdmUiOnRydWUsInByZXZpZXciOnRydWUsImZpZWxkcyI6W119fQ.abc123"
  data-language="en"
  data-autosave="true"
  data-preview="true"
  data-with-title="true"
  data-with-send-button="true"
  data-with-recipients="true"
></docuseal-builder>
```

<CardGroup cols={2}>
  <Card title="Signing Form" icon="file-signature" href="/embed/signing-form">
    Embed a signing form with pre-fill, events, and redirect support.
  </Card>

  <Card title="Template Builder" icon="hammer" href="/embed/template-builder">
    Embed the template editor with field configuration and save hooks.
  </Card>
</CardGroup>

### 2. JavaScript SDK

A global `window.DocuTrust` API for programmatic control. Use the SDK when you need imperative mounting, event handling, or dynamic configuration that goes beyond static HTML attributes.

```javascript theme={null}
DocuTrust.configure({
  host: 'https://your-app.com'
});

const form = DocuTrust.mount({
  element: '#signing-container',
  submitterSlug: 'aB3kL9mNpQ',
  email: 'jane.doe@example.com',
  withTitle: true,
  withDownloadButton: true,
  withSendCopyButton: true,
  allowToResubmit: false,
  language: 'en',
  values: { 'Full Name': 'Jane Doe', 'Email': 'jane.doe@example.com' },
  completedRedirectUrl: 'https://your-app.com/thank-you'
});

DocuTrust.on('completed', (detail) => {
  console.log('Submission completed:', detail);
});
```

<Card title="JavaScript SDK" icon="js" href="/embed/sdk">
  Full SDK reference with mount, configure, and event APIs.
</Card>

### 3. Direct iframe

For maximum control, build your own iframe pointing to the signing URL with the `embed=true` query parameter. This approach gives you full control over iframe sizing, sandboxing, and cross-origin communication.

```html theme={null}
<iframe
  id="docutrust-frame"
  src="https://your-app.com/s/aB3kL9mNpQ?embed=true"
  width="100%"
  height="800"
  frameborder="0"
  allow="camera; microphone"
  style="border: none;"
></iframe>

<script>
  window.addEventListener('message', function (event) {
    if (event.origin !== 'https://your-app.com') return;

    var data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;

    if (data.type === 'completed') {
      console.log('Submitter ID:', data.detail.submitter_id);
      console.log('Submission ID:', data.detail.submission_id);
      console.log('Audit log URL:', data.detail.audit_log_url);
      console.log('Documents:', data.detail.documents);
    }

    if (data.type === 'docutrust:resize') {
      var iframe = document.getElementById('docutrust-frame');
      iframe.style.height = data.detail.height + 'px';
    }
  });
</script>
```

With a direct iframe you are responsible for:

* Resizing the iframe to match content height (listen for `docutrust:resize` messages)
* Listening to `postMessage` events from the iframe for completion and field changes
* Passing configuration via query parameters instead of `data-*` attributes

**Supported query parameters:**

| Parameter                | Example                     | Description                  |
| ------------------------ | --------------------------- | ---------------------------- |
| `embed`                  | `true`                      | Enable embed mode (required) |
| `email`                  | `jane@example.com`          | Pre-fill signer email        |
| `name`                   | `Jane Doe`                  | Pre-fill signer name         |
| `language`               | `es`                        | UI language code             |
| `with_title`             | `false`                     | Hide the form title          |
| `completed_redirect_url` | `https://your-app.com/done` | Redirect after completion    |

## Decision Matrix

Use this table to choose the right approach for your integration.

| Criteria               | Web Components                          | JavaScript SDK                       | Direct iframe                          |
| ---------------------- | --------------------------------------- | ------------------------------------ | -------------------------------------- |
| **Ease of use**        | Easiest -- HTML attributes only         | Moderate -- requires JS              | Manual -- you handle everything        |
| **Setup time**         | Minutes                                 | Minutes                              | Hours                                  |
| **Flexibility**        | High -- 18 attributes, 6 events         | Highest -- full programmatic control | Full control, but more work            |
| **Framework support**  | Any (HTML, React, Vue, Angular, Svelte) | Any with JS access                   | Any that supports iframes              |
| **Event handling**     | `addEventListener` on the element       | `DocuTrust.on()` chaining API        | Raw `window.postMessage`               |
| **Auto-resize**        | Built-in                                | Built-in                             | Manual (listen for `docutrust:resize`) |
| **Configuration**      | Declarative `data-*` attributes         | Imperative options object            | Query parameters                       |
| **Pre-fill support**   | JSON via `data-values` attribute        | Object via `values` option           | Limited to query parameters            |
| **TypeScript support** | N/A                                     | Full type definitions                | N/A                                    |
| **Bundle size**        | \~8 KB (embed script)                   | \~8 KB (same script)                 | 0 KB (no script needed)                |
| **Best for**           | Most integrations                       | SPAs needing dynamic control         | Existing iframe infrastructure         |

<Note>
  For most integrations, **Web Components** are the recommended approach. They provide the best balance of simplicity and flexibility with zero framework dependencies.
</Note>

## Authentication for Embedding

Both the signing form and the template builder support token-based authentication via JWT. Tokens are generated server-side through the `/api/embed/token` endpoint and scoped to a single submission or template.

* **Signing forms** can use either a submitter slug (public link) or a JWT token for authenticated access.
* **Template builders** always require a JWT token generated server-side.

Tokens use HS256 signing with configurable expiration (default 4 hours) and are scoped by audience (`form` or `builder`).

<Card title="JWT Tokens" icon="key" href="/embed/jwt-tokens">
  Server-side token generation, claim structure, and security best practices.
</Card>