Signing Form Web Component

The <docuseal-form> web component renders a fully functional signing form inside your application. Signers can view the document, fill in fields, draw signatures, and submit — all without leaving your page.

Quick start

Add the embed script and drop in the component:

<script src="https://your-app.com/js/spitshake-embed.js"></script>

<docuseal-form
  data-src="https://your-app.com/s/aB3kL9mNpQ"
></docuseal-form>

That is all you need to render a working signing form. The sections below cover every available attribute and event.

Attributes

The <docuseal-form> component accepts 39 data-* attributes to control behavior, pre-fill data, and customize the UI.

Attribute	Type	Default	Description
`data-src`	string	required	Signing form URL. Format: `https://your-app.com/s/SLUG` where `SLUG` is the submitter’s unique signing slug.
`data-email`	string	—	Pre-fill the signer’s email address. When provided, the email step is skipped.
`data-name`	string	—	Pre-fill the signer’s display name. When the submission uses `quick_sign_mode: "confirmation_modal"`, this name is also used to auto-generate a cursive signature (Dancing Script font) and initials in the signing carousel.
`data-role`	string	—	Target a specific submitter role (e.g., `"Recipient"`, `"Witness"`). Required when the submission has multiple roles sharing the same email.
`data-preview`	`"true"`	—	Enable preview mode. The form renders all fields but disables submission. Useful for showing a read-only view of the document.
`data-language`	string	—	UI language code. Supported values: `"en"`, `"es"`, `"fr"`, `"de"`, `"pt"`, `"it"`, `"nl"`, `"ja"`, `"zh"`, `"ko"`, `"ar"`, `"he"`.
`data-with-title`	`"false"`	`"true"`	Set to `"false"` to hide the template title at the top of the form.
`data-with-send-copy-button`	`"false"`	`"true"`	Set to `"false"` to hide the “Send a copy” button that lets the signer email themselves a copy.
`data-with-download-button`	`"false"`	`"true"`	Set to `"false"` to hide the download button on the completion screen.
`data-allow-to-resubmit`	`"true"`	`"false"`	Set to `"true"` to allow the signer to resubmit the form after initial completion.
`data-go-to-last`	`"true"`	—	When set, the form automatically scrolls to the last incomplete field on load. Useful for returning signers who previously started filling out the form.
`data-skip-fields`	string	—	Comma-separated list of field names to skip. Skipped fields are hidden from the signer and not required. Example: `"Internal Notes,Manager Approval"`.
`data-values`	JSON string	—	Pre-fill field values as a JSON object. Keys are field names, values are the pre-filled content. Example: `'{"Full Name": "Jane Doe", "Company": "Acme Inc"}'`.
`data-metadata`	JSON string	—	Attach custom metadata to the submission as a JSON object. Metadata is returned in webhook payloads and API responses. Example: `'{"customer_id": "cust_8472", "deal_id": "deal_291"}'`.
`data-readonly-fields`	string	—	Comma-separated list of field names to render as read-only. The signer can see the value but cannot edit it. Example: `"Contract Amount,Start Date"`.
`data-completed-redirect-url`	string	—	Has no effect. The signing page ignores it. Set the redirect on the server with `completed_redirect_url` instead; see Redirect after completion.
`data-expand`	`"true"`	—	Expand the form iframe to its full content height, eliminating internal scrolling. The form integrates seamlessly into the page layout.
`data-minimize-first-step`	`"true"`	—	Collapse the first step (usually email/name entry) into a compact bar. The signer clicks to expand it. Useful when you pre-fill email/name and want to reduce visual noise.
`data-autoscroll`	`"false"`	`"true"`	Set to `"false"` to disable automatic scrolling to the next field after the signer completes one.
`data-external-id`	string	—	Link the signer to an external ID in your system. The value is stored on the submitter and returned in webhook payloads and API responses.
`data-token`	string	—	JWT token for authentication. Use this instead of `data-src` when you generate a signing token server-side via `POST /api/embed/token` with `audience: "form"`.
`data-logo`	string	—	URL to a custom logo image displayed at the top of the signing form. Overrides the account-level logo.
`data-i18n`	JSON string	—	Custom i18n key overrides as a JSON object. Allows you to replace specific UI strings in the signing form. Example: `'{"submit": "Confirm & Sign", "next": "Continue"}'`.
`data-with-decline`	`"true"`	—	Set to `"true"` to show a “Decline” button, allowing the signer to decline the document. Fires the `declined` event when clicked.
`data-with-field-names`	`"false"`	`"true"`	Set to `"false"` to hide field labels/names above each input in the signing form.
`data-with-field-placeholder`	string	—	Show placeholder text inside empty fields. The string value is used as the placeholder for text-type fields.
`data-with-complete-button`	`"false"`	`"true"`	Set to `"false"` to hide the complete/submit button. Useful when you want to control submission programmatically.
`data-only-required-fields`	`"true"`	—	When set to `"true"`, only required fields are shown to the signer. Optional fields are hidden.
`data-allow-typed-signature`	`"false"`	`"true"`	Set to `"false"` to disable the typed signature option in the signature pad. Only drawn and uploaded signatures will be available.
`data-signature`	string	—	Pre-fill the signature field with a base64-encoded image (`data:image/png;base64,...`), an image URL, or plain text (rendered as a typed signature in cursive). Directly sets the signature value — bypasses the carousel. For the 2-step QuickSign carousel UX, use `data-name` with `confirmation_modal` mode instead.
`data-send-copy-email`	`"false"`	`"true"`	Set to `"false"` to disable the option for the signer to send themselves a copy of the signed document via email.
`data-order-as-on-page`	`"true"`	—	When set to `"true"`, fields are ordered by their position on the page (top to bottom, left to right) rather than the order defined in the template schema.
`data-background-color`	string	—	Background color for the signing form as a HEX code (e.g., `"#f3f4f6"`). Overrides the default white background.
`data-custom-css`	string	—	Custom CSS rules injected into the signing form iframe. Allows overriding default styles for advanced branding. Example: `"body { font-family: 'Inter', sans-serif; } .field-label { color: #1e3a5f; }"`.
`data-completed-message-title`	string	—	Custom title displayed on the completion screen after the signer submits. Replaces the default “Document signed” heading. Example: `"Thank you for signing!"`.
`data-completed-message-body`	string	—	Custom body text displayed on the completion screen. Replaces the default completion message. Supports basic HTML. Example: `"Your signed document will be emailed to you shortly."`.
`data-completed-button-title`	string	—	Custom text for the button on the completion screen. Replaces the default button label. Example: `"Return to Dashboard"`.
`data-completed-button-url`	string	—	Custom URL for the completion screen button. When set, clicking the button navigates to this URL instead of the default behavior. Example: `"https://your-app.com/dashboard"`.
`data-minimize`	`"true"`	—	When set to `"true"`, field panels are always minimized (collapsed). The signer clicks on a field area to expand it. Reduces visual clutter on documents with many fields.
`data-autoscroll-fields`	`"false"`	`"true"`	Alias for `data-autoscroll`. Set to `"false"` to disable automatic scrolling to the next field after the signer completes one.

QuickSign recipe (2-click signing)

Combine data-name on the embed with confirmation_modal mode on the submission for a 2-click signing experience: ESIGN consent → signature carousel → done. Step 1 — Create the submission (server-side):

POST /api/submissions
{
  "template_id": "tpl_7VQhP2tM9xA1kR8bN",
  "send_email": false,
  "quick_sign_mode": "confirmation_modal",
  "submitters": [{
    "email": "jane@example.com",
    "name": "Jane Smith",
    "role": "Client",
    "values": {
      "Company Name": "Acme Corp",
      "EIN": "12-3456789",
      "Effective Date": "2026-04-22"
    }
  }],
  "prefill_behavior": {
    "skip_if_prefilled": true,
    "editable_if_prefilled": false
  },
  "preferences": {
    "completed_redirect_url": "https://yourapp.com/done"
  }
}

Step 2 — Embed the signing form (client-side):

<docuseal-form
  data-src="https://spitshake.io/s/{slug_from_step_1}"
  data-name="Jane Smith"
  data-with-title="false"
/>

What the signer sees:

ESIGN consent modal — “I Agree & Continue”
Bottom-sheet carousel with 2 steps:
- Signature — auto-generated in Dancing Script cursive from data-name, with REDRAW option
- Initials — auto-generated from name initials (e.g. “JS”), with REDRAW option
Each signature/initials value is applied to ALL fields of that type across all pages
Pre-filled text fields render as read-only overlays on the document (visible but not editable)
After submission, your page is redirected to the completed_redirect_url from step 1

data-name vs data-signature: Use data-name for the carousel UX (auto-generates cursive, signer can redraw). Use data-signature to directly pre-fill a specific signature image or text without the carousel. Both work — data-name gives the better interactive experience.

The carousel only triggers when ALL required non-signature fields have values. If required text fields are empty, the form falls back to field-by-field mode. Make sure to pre-fill all required fields via the values parameter.

Full HTML example

This example demonstrates every available attribute:

<script src="https://your-app.com/js/spitshake-embed.js"></script>

<docuseal-form
  id="signing-form"
  data-src="https://your-app.com/s/aB3kL9mNpQ"
  data-email="jane.doe@example.com"
  data-name="Jane Doe"
  data-role="Recipient"
  data-external-id="usr_9f84b2a1"
  data-token="eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxNDIiLCJpc3MiOiJkb2N1dHJ1c3QiLCJhdWQiOiJmb3JtIn0.xyz789"
  data-logo="https://your-app.com/assets/logo.png"
  data-language="en"
  data-preview="false"
  data-with-title="true"
  data-with-send-copy-button="true"
  data-with-download-button="true"
  data-with-decline="true"
  data-with-field-names="true"
  data-with-field-placeholder="Enter value here"
  data-with-complete-button="true"
  data-only-required-fields="false"
  data-allow-to-resubmit="false"
  data-allow-typed-signature="true"
  data-go-to-last="true"
  data-autoscroll="true"
  data-expand="true"
  data-minimize-first-step="true"
  data-order-as-on-page="false"
  data-send-copy-email="true"
  data-background-color="#ffffff"
  data-custom-css="body { font-family: 'Inter', sans-serif; } .field-label { color: #1e3a5f; }"
  data-completed-message-title="Thank you for signing!"
  data-completed-message-body="Your signed document will be emailed to you shortly."
  data-completed-button-title="Return to Dashboard"
  data-completed-button-url="https://your-app.com/dashboard"
  data-minimize="false"
  data-autoscroll-fields="true"
  data-skip-fields="Internal Notes"
  data-readonly-fields="Contract Amount,Start Date"
  data-signature="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  data-values='{
    "Full Name": "Jane Doe",
    "Email": "jane.doe@example.com",
    "Company": "Acme Inc",
    "Title": "VP of Operations",
    "Date": "2026-04-08"
  }'
  data-metadata='{
    "customer_id": "cust_8472",
    "deal_id": "deal_291",
    "plan": "enterprise",
    "source": "onboarding_flow"
  }'
  data-i18n='{
    "submit": "Confirm & Sign",
    "next": "Continue",
    "decline": "Decline to Sign",
    "type_here": "Start typing..."
  }'
></docuseal-form>

Events

The <docuseal-form> component emits DOM custom events that you can listen to with addEventListener. Every event provides a detail property on the event object with relevant data.

init

Fired when the web component is initialized and the iframe begins loading.

document.getElementById('signing-form').addEventListener('init', function (event) {
  console.log('Form iframe is loading');
});

Event detail: { component }, the <docuseal-form> element.

load

Fired when the iframe has loaded and the form is ready to render.

document.getElementById('signing-form').addEventListener('load', function (event) {
  console.log('Form iframe loaded');
});

Event detail: { iframe }, the iframe element.

loaded

Fired when the form content has fully rendered and is interactive.

document.getElementById('signing-form').addEventListener('loaded', function (event) {
  console.log('Form ready:', event.detail);
});

Event detail:

{
  "submitter": "aB3kL9mNpQ"
}

submitter is the signer’s slug (the last part of the signing link).

completed

Fired when the signer successfully submits the form. The event is cancelable: when redirect_url is an http(s) URL, the component redirects your page to it after the event unless a listener calls event.preventDefault().

document.getElementById('signing-form').addEventListener('completed', function (event) {
  var data = event.detail;
  console.log('Signer finished:', data.submitter);
  // Keep the signer on this page and update your UI instead:
  // event.preventDefault();
});

Event detail:

{
  "submitter": "aB3kL9mNpQ",
  "redirect_url": "https://your-app.com/signing-complete"
}

Key	Description
`submitter`	The signer’s slug.
`redirect_url`	The `completed_redirect_url` resolved for this signer (see Redirect after completion), or `null` when none is set.

The event carries no document, field or submission data. Fetch those from the API, or use the submission.completed / form.completed webhooks.

declined

Fired when the signer declines to sign the document.

document.getElementById('signing-form').addEventListener('declined', function (event) {
  var data = event.detail;
  console.log('Signer declined:', data.reason);
});

Event detail:

{
  "submitter": "aB3kL9mNpQ",
  "reason": "Terms not acceptable"
}

field-value

Fired each time the signer fills in or changes a field value.

document.getElementById('signing-form').addEventListener('field-value', function (event) {
  var data = event.detail;
  console.log('Field changed:', data.field_uuid, '=', data.value);
});

Event detail:

{
  "field_uuid": "3f0c9b1e-8a2d-4c55-9e1a-2b7d6c4f8a10",
  "value": "Jane Doe"
}

spitshake:resize

Fired when the form content height changes. Used internally by the web component to auto-resize the iframe. If you use a direct iframe, listen for this event to sync the iframe height. Event detail:

{
  "height": 1247
}

React integration

Use the web component directly in React with a ref for event handling:

import { useEffect, useRef, useCallback } from 'react';

function SigningForm({ slug, signerEmail, signerName }) {
  const formRef = useRef(null);

  const handleCompleted = useCallback((event) => {
    const data = event.detail;
    console.log('Signer finished:', data.submitter);
    // Stay in the app instead of following the server-side redirect
    event.preventDefault();
    window.location.href = `/signing/${data.submitter}/success`;
  }, []);

  const handleDeclined = useCallback((event) => {
    const data = event.detail;
    console.log('Signer declined:', data.reason);
    // Show a message or redirect
  }, []);

  const handleFieldValue = useCallback((event) => {
    const data = event.detail;
    console.log(`Field ${data.field_uuid} set to:`, data.value);
  }, []);

  useEffect(() => {
    const el = formRef.current;
    if (!el) return;

    el.addEventListener('completed', handleCompleted);
    el.addEventListener('declined', handleDeclined);
    el.addEventListener('field-value', handleFieldValue);

    return () => {
      el.removeEventListener('completed', handleCompleted);
      el.removeEventListener('declined', handleDeclined);
      el.removeEventListener('field-value', handleFieldValue);
    };
  }, [handleCompleted, handleDeclined, handleFieldValue]);

  return (
    <docuseal-form
      ref={formRef}
      data-src={`https://your-app.com/s/${slug}`}
      data-email={signerEmail}
      data-name={signerName}
      data-role="Recipient"
      data-external-id="usr_9f84b2a1"
      data-logo="https://your-app.com/assets/logo.png"
      data-language="en"
      data-with-title="true"
      data-with-send-copy-button="true"
      data-with-download-button="true"
      data-with-decline="true"
      data-with-field-names="true"
      data-with-field-placeholder="Enter value here"
      data-with-complete-button="true"
      data-only-required-fields="false"
      data-allow-to-resubmit="false"
      data-allow-typed-signature="true"
      data-go-to-last="true"
      data-expand="true"
      data-autoscroll="true"
      data-order-as-on-page="false"
      data-send-copy-email="true"
      data-background-color="#ffffff"
      data-custom-css="body { font-family: 'Inter', sans-serif; } .field-label { color: #1e3a5f; }"
      data-completed-message-title="Thank you for signing!"
      data-completed-message-body="Your signed document will be emailed to you shortly."
      data-completed-button-title="Return to Dashboard"
      data-completed-button-url="https://your-app.com/dashboard"
      data-minimize="false"
      data-autoscroll-fields="true"
      data-values={JSON.stringify({
        'Full Name': signerName,
        'Email': signerEmail,
        'Company': 'Acme Inc',
        'Title': 'VP of Operations',
        'Date': '2026-04-08'
      })}
      data-metadata={JSON.stringify({
        customer_id: 'cust_8472',
        deal_id: 'deal_291',
        plan: 'enterprise',
        source: 'react_app'
      })}
      data-i18n={JSON.stringify({
        submit: 'Confirm & Sign',
        next: 'Continue'
      })}
    />
  );
}

export default SigningForm;

Remember to include the embed script in your HTML. In React, add it to your index.html or load it dynamically:

<script src="https://your-app.com/js/spitshake-embed.js"></script>

Vue integration

<template>
  <docuseal-form
    ref="formEl"
    :data-src="`https://your-app.com/s/${slug}`"
    :data-email="signerEmail"
    :data-name="signerName"
    data-role="Recipient"
    data-external-id="usr_9f84b2a1"
    data-logo="https://your-app.com/assets/logo.png"
    data-language="en"
    data-with-title="true"
    data-with-send-copy-button="true"
    data-with-download-button="true"
    data-with-decline="true"
    data-with-field-names="true"
    data-with-field-placeholder="Enter value here"
    data-with-complete-button="true"
    data-only-required-fields="false"
    data-allow-to-resubmit="false"
    data-allow-typed-signature="true"
    data-expand="true"
    data-autoscroll="true"
    data-order-as-on-page="false"
    data-send-copy-email="true"
    data-background-color="#ffffff"
    data-custom-css="body { font-family: 'Inter', sans-serif; }"
    data-completed-message-title="Thank you for signing!"
    data-completed-message-body="Your signed document will be emailed to you shortly."
    data-completed-button-title="Return to Dashboard"
    data-completed-button-url="https://your-app.com/dashboard"
    data-minimize="false"
    data-autoscroll-fields="true"
    :data-values="JSON.stringify({ 'Full Name': signerName, 'Email': signerEmail, 'Company': 'Acme Inc' })"
    :data-metadata="JSON.stringify({ customer_id: customerId, source: 'vue_app' })"
    :data-i18n="JSON.stringify({ submit: 'Confirm & Sign', next: 'Continue' })"
  />
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';

const props = defineProps({
  slug: { type: String, required: true },
  signerEmail: { type: String, required: true },
  signerName: { type: String, required: true },
  customerId: { type: String, default: '' },
  redirectUrl: { type: String, default: '' }
});

const emit = defineEmits(['completed', 'declined', 'fieldValue']);

const formEl = ref(null);

function onCompleted(event) {
  emit('completed', event.detail);
}

function onDeclined(event) {
  emit('declined', event.detail);
}

function onFieldValue(event) {
  emit('fieldValue', event.detail);
}

onMounted(() => {
  const el = formEl.value;
  if (!el) return;
  el.addEventListener('completed', onCompleted);
  el.addEventListener('declined', onDeclined);
  el.addEventListener('field-value', onFieldValue);
});

onUnmounted(() => {
  const el = formEl.value;
  if (!el) return;
  el.removeEventListener('completed', onCompleted);
  el.removeEventListener('declined', onDeclined);
  el.removeEventListener('field-value', onFieldValue);
});
</script>

Pre-filling fields

Use data-values to pre-populate form fields. The JSON object maps field names (as defined in the template) to their values.

<docuseal-form
  data-src="https://your-app.com/s/aB3kL9mNpQ"
  data-email="jane.doe@example.com"
  data-name="Jane Doe"
  data-signature="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  data-values='{
    "Full Name": "Jane Doe",
    "Email": "jane.doe@example.com",
    "Company": "Acme Inc",
    "Title": "VP of Operations",
    "Start Date": "2026-04-08",
    "Salary": "150000",
    "Department": "Engineering",
    "Office Location": "San Francisco"
  }'
></docuseal-form>

Use data-signature to pre-fill the signature field. Accepted formats: a base64-encoded image (data:image/png;base64,...), an HTTPS image URL, or plain text that renders as a typed signature.

Supported field types for pre-fill:

Field Type	Value Format	Example
`text`	String	`"Jane Doe"`
`date`	ISO date string	`"2026-04-08"`
`number`	Numeric string	`"150000"`
`checkbox`	`"true"` or `"false"`	`"true"`
`select`	Option value string	`"Option B"`
`radio`	Option value string	`"Yes"`
`phone`	E.164 format	`"+14155551234"`
`cells`	String (one char per cell)	`"ABC123"`

Signature, initials, image, file, and stamp fields cannot be pre-filled via data-values. These require the signer to provide them interactively.

Redirect after completion

The redirect is set on the server, not on the embed. Pass completed_redirect_url when you create the submission (for everyone) or on a signer (for that signer only). The template’s redirect_url is the fallback. See Redirect after signing for the full order.

POST /api/submissions
{
  "template_id": "tpl_7VQhP2tM9xA1kR8bN",
  "completed_redirect_url": "https://your-app.com/signing-complete",
  "submitters": [{ "role": "Recipient", "email": "jane.doe@example.com" }]
}

The URL must be an absolute http(s) URL (otherwise 422 with "code": "invalid_redirect_url") and is used as given: SpitShake adds no query parameters. Put your own identifiers in it when you create the submission. When the signer submits, the signing page sends spitshake:completed with the redirect_url, and <docuseal-form> fires its completed event and then redirects your page to that URL. Call event.preventDefault() in a completed listener to handle it yourself:

form.addEventListener('completed', (event) => {
  event.preventDefault()
  showThankYou(event.detail.submitter)
})

The signing page also tries to move the top window to the URL about half a second after submitting, and the browser may allow it. To be sure the signer stays on your page, create the submission without a redirect URL.

data-completed-redirect-url on the component has no effect.

Reopened links and stale tabs

A signer who opens the signing link again after finishing, or who still has the form open in another tab, gets an Already Completed page. When a redirect URL is set it shows a Continue link to it, opened in the top window. It does not redirect on its own, and the component’s completed event does not fire again. A stale tab’s save or submit is refused with 422 and {"error": "Already completed", "code": "already_completed"}, and the page reloads to show Already Completed.

postMessage events

When the signing form is embedded in an iframe (either via the web component or a raw <iframe>), the form communicates with the parent window via postMessage. Each message is { type: "spitshake:<event>", data }; the payload is in event.data.data. Listen for these events to react to signing lifecycle changes without polling.

window.addEventListener('message', (event) => {
  if (!event.data?.type?.startsWith('spitshake:')) return

  switch (event.data.type) {
    case 'spitshake:completed':
      console.log('Signed!', event.data.data)
      break
    case 'spitshake:declined':
      console.log('Declined', event.data.data)
      break
  }
})

Event	Fired when	Payload
`spitshake:loaded`	The signing form iframe has loaded and is ready.	`{ submitter: "slug" }`
`spitshake:completed`	The signer has submitted all fields successfully.	`{ submitter: "slug", redirect_url }` (`redirect_url` is `null` when none is set)
`spitshake:declined`	The signer declined to sign.	`{ submitter: "slug", reason }`
`spitshake:field-value`	A field value changed (useful for live sync).	`{ field_uuid, value }`
`spitshake:resize`	The iframe content height changed (for auto-sizing).	`{ height: 1200 }`

Use spitshake:completed as the trigger for your front-end workflow. It fires before any redirect. With a raw <iframe>, the signing page’s own attempt to move your page may be blocked by the browser, so read redirect_url from the payload and navigate yourself. For backend work (marking the agreement as signed), rely on webhooks, which also fire when the signer uses the emailed link.

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

Signing Form

Signing Form Web Component

Quick start

Attributes

QuickSign recipe (2-click signing)

Full HTML example

Events

init

load

loaded

completed

declined

field-value

spitshake:resize

React integration

Vue integration

Pre-filling fields

Redirect after completion

Reopened links and stale tabs

postMessage events

​Signing Form Web Component

​Quick start

​Attributes

​QuickSign recipe (2-click signing)

​Full HTML example

​Events

​init

​load

​loaded

​completed

​declined

​field-value

​spitshake:resize

​React integration

​Vue integration

​Pre-filling fields

​Redirect after completion

​Reopened links and stale tabs

​postMessage events

Signing Form Web Component

Quick start

Attributes

QuickSign recipe (2-click signing)

Full HTML example

Events

init

load

loaded

completed

declined

field-value

spitshake:resize

React integration

Vue integration

Pre-filling fields

Redirect after completion

Reopened links and stale tabs

postMessage events