Visual Forms JavaScript API

Open in Claude Open in ChatGPT

The Visual Forms JavaScript library allows you to embed a visual PDF form directly on your website so that your users can fill it out and generate a PDF. It doesn’t provide the compliance and audit trail features of signature requests, but it provides more flexibility and has many options for customization and styling.

Implementation Guide for Visual FormsStep-by-step guide to embedding visual forms on your website

Visual Forms ChangelogChangelog entries for the Visual Forms JavaScript library

DocSpring.createVisualForm()

Creates an embedded visual form for filling out PDF templates.

Syntax

DocSpring.createVisualForm(cssSelector, optionsAndCallbacks);

The form is rendered inline, inside the container element. Visual forms don’t have a modal mode.

Parameters

Parameter	Type	Required	Description
`cssSelector`	string	Yes	CSS selector for the container element where the form will be rendered
`optionsAndCallbacks`	object	Yes	Configuration options and event callbacks

Required Options

Option	Type	Description
`templateId`	string	Your Template ID

Configuration Options

Option	Type	Default	Description
`templateVersion`	string	`null`	The template version to show and submit, e.g. `"1.2.3"` or `"draft"`. Defaults to the latest published version, or the draft if no version is published.
`templateData`	object	`null`	Cached template data (alternative to `templateId`)
`defaultFormData`	object	`{}`	Default values for fields (can be changed by the user)
`staticFormData`	object	`{}`	Static values for fields (cannot be changed by the user)
`fieldOverrides`	object	`{}`	Override field properties like `hidden` or `backgroundColor`. On a public template, a submission from anyone but your own account keeps only `hidden`, `required` and `backgroundColor`
`redirectURL`	string	`null`	Redirect to this URL after submitting the form. It can have variables after its `?` or `#`.
`redirectURLQueryParams`	boolean	`true`	Add `submission_id`, `template_id`, and `template_name` query params to the redirect URL
`waitForPDF`	boolean	`true`	Set to `false` to show the thank-you title as soon as the form is saved, without the PDF processing message. The Download PDF button still appears when the PDF is ready, and the form still waits for the PDF before redirecting
`test`	boolean or function	`false`	Create a test submission instead of a live submission. A function is called when the form is submitted and returns `true` or `false` (from version 2.15.0)
`metadata`	object	`null`	Saved with the submission as its `metadata` (from version 2.15.0)
`focusFirstFieldOnLoad`	boolean	`false`	Automatically focus the first field when the form loads
`showSignatureModalOnFocus`	boolean	`false`	Open signature modal automatically when signature field is focused
`showHeader`	boolean	`true`	Show the form header with navigation buttons
`adjustHeaderOnScroll`	boolean	`true`	Keep header at top of page when scrolling
`showClearButton`	boolean	`true`	Show the “Clear Form” button
`showTermsOfServiceLink`	boolean	`true`	Show the terms of service link
`skipAgreeToTermsOfService`	boolean	`false`	Skip the “agree to terms” step
`allowSkippingOptionalFields`	boolean	`null`	Set to `true` to show the “Continue” button as soon as every required field is filled in, without first going through each optional field with “Next”. Set to `false` to always go through the optional fields. Overrides the template’s “Show Continue Once Required Fields Are Filled In” setting, which is used when this is `null` (Requires Visual Forms JS 2.16.0 or above)
`previewMode`	boolean	`false`	Show form in preview mode with a single “Close” button
`previewModeButtonLabel`	string	`"Close"`	Label for the preview mode button
`termsOfServiceLabel`	string	`"DocSpring Terms of Service"`	Label for terms of service link
`termsOfServiceURL`	string	DocSpring ToS	URL for terms of service
`showPdfProcessingSpinner`	boolean	`true`	Show spinner while PDF is processing
`downloadButtonLabel`	string	`"Download PDF"`	Label for the download button
`region`	string	`US`	Use a DocSpring region: `US` or `EU`
`host`	string	`null`	Use one host for both app and API URLs, usually for single-domain enterprise deployments
`appHost`	string	`null`	Override the app host used for template data and page images
`apiHost`	string	`null`	Not used from version 2.22.0, which sends the submission to `appHost`. Earlier versions send submission and polling requests here

Region and Custom Host

Use region when your account is in the EU region:

DocSpring.createVisualForm('.form-container', {
templateId: 'tpl_123456',
region: 'EU'
})

For single-domain enterprise deployments, use host:

DocSpring.createVisualForm('.form-container', {
templateId: 'tpl_123456',
host: 'https://docspring.example.com'
})

For split-domain deployments, use appHost (and apiHost before version 2.22.0). Existing globals such as DocSpring.region, DocSpring.appHost, DocSpring.apiHost, DocSpring.host, DocSpring.scheme, and DocSpring.port are still supported.

String Options

Customize the titles and messages shown in the form. These options can be either a plain string or a function that returns a string.

Option	Function Arguments	Description
`pdfProcessingTitle`	`template` (object)	Title when PDF is being processed
`pdfProcessingMessage`	`template` (object)	Message when PDF is being processed
`completedTitle`	`template` (object), `downloadURL` (string)	Title when PDF is ready for download
`completedTitleNoDownload`	`template` (object)	Title when form is submitted (no download)
`pdfProcessedMessage`	`template` (object), `downloadURL` (string)	Message when PDF is ready
`footerHTML`	`template` (object)	Custom HTML for the footer

Callbacks

Callback	Parameters	Description
`onInitialize`	-	Called when the form has been initialized
`onLoad`	-	Called when all form pages have been loaded
`onClearForm`	-	Called when the form is cleared
`onFieldFocus`	`{ id, name, value }`	Called when a field gains focus
`onFieldBlur`	`{ id, name, value }`	Called when a field loses focus
`onFieldChange`	`{ id, name, value, previousValue }`	Called when a field value changes
`onShowAcceptTerms`	-	Called when showing the “accept terms” screen
`onSubmit`	`formData` (object)	Called when the form is submitted
`onSave`	`submissionId` (string)	Called when the submission is saved
`onProcessed`	`{ submissionId, downloadURL }`	Called when the PDF is processed. If the form redirects, the redirect follows one second later (from version 2.12.0; older versions don’t call it when the form redirects)
`onError`	`error`	Called if an error occurs
`onPreviewModeButtonClicked`	-	Called when preview mode button is clicked

Global Functions

These global functions allow you to interact with the form. Note that only one DocSpring form can be displayed on a page.

Function	Parameters	Description
`DocSpring.clearForm()`	-	Clear all data and reset to defaults
`DocSpring.submitForm()`	-	Submit the form (shows validation errors if any)
`DocSpring.focusNextField()`	-	Focus the next field
`DocSpring.focusField(name_or_id)`	`name_or_id`: Field name or numeric ID	Focus a specific field
`DocSpring.setField(name_or_id, value)`	`name_or_id`: Field name or numeric ID `value`: Value to set	Set a field’s value
`DocSpring.getFormData()`	-	Return the values entered in the form, as an object like the `data` of a submission. Default values (from the template or `defaultFormData`), static values and formula results are left out (from version 2.15.0)
`DocSpring.setFormData(data)`	`data`: An object like the `data` of a submission	Replace the values entered in the form. Fields that `data` leaves out go back to their default values. Static fields, and fields set with `staticFormData`, keep their values (from version 2.15.0)
`DocSpring.returnToForm()`	-	Return to the form after it has been submitted

Examples

Basic Usage

DocSpring.createVisualForm('.form-container', {
  templateId: 'tpl_123456'
})

With Pre-filled Data

DocSpring.createVisualForm('.form-container', {
  templateId: 'tpl_123456',

  // Default values (user can change)
  defaultFormData: {
    customer: {
      name: 'John Smith',
      email: '[email protected]'
    }
  },

  // Static values (user cannot change)
  staticFormData: {
    invoice_number: 'INV-2024-001',
    date: '2024-01-15'
  }

})

A field that is Static in the template always shows the template’s value, which the PDF prints: the form ignores its values in defaultFormData and staticFormData. If the template allows additional properties, the form keeps those values and submits them.

Custom Configuration

DocSpring.createVisualForm('.form-container', {
  templateId: 'tpl_123456',

  // Skip terms and auto-focus first field
  skipAgreeToTermsOfService: true,
  focusFirstFieldOnLoad: true,

  // Callbacks
  onFieldChange: function(field) {
    console.log('Field changed:', field.name, field.value);
  },

  onSubmit: function(formData) {
    console.log('Submitting:', formData);
  },

  onProcessed: function(data) {
    console.log('PDF ready:', data.downloadURL);
    // Custom download handling
    window.location.href = data.downloadURL;
  }

})

If the form has a redirect URL (from the redirectURL option or the template’s settings), it calls onProcessed first and redirects one second later, so the callback has time to finish. (Before version 2.12.0, the form redirected without calling onProcessed.)

Field Overrides

DocSpring.createVisualForm('.form-container', {
  templateId: 'tpl_123456',

  // Hide certain fields or change properties
  fieldOverrides: {
    internal_notes: {
      hidden: true
    },
    signature: {
      backgroundColor: 'FFFEF0'
    }
  }

})

Preview Mode

DocSpring.createVisualForm('.form-container', {
  templateId: 'tpl_123456',

  // Show form in preview mode
  previewMode: true,
  previewModeButtonLabel: 'Close Preview',

  // Pre-fill with sample data
  staticFormData: {
    customer: { name: 'Sample Customer' },
    amount: 1000
  },

  onPreviewModeButtonClicked: function() {
    console.log('Preview closed');
    // Hide the preview container
  }

})

Signature fields

Signatures come only from signature requests, which record who signed and when. In a form with a signature or initials field (from version 2.22.0):

In test mode (the test option, or the Test switch on your template’s hosted form), the signature pad works, and a warning at the top of the form says it’s for testing.
A live form says at the top that it can’t be signed as soon as it loads, even when the signature field is on a later page. Its signature fields say “Test mode only” and don’t open, and it can’t be submitted. DocSpring rejects a live submission with a signature or initials value too.

To print an image or a name on the PDF without a signature request, use an Image or Text field.

On a DocSpring Enterprise install, signature fields work in live forms too.

Field Types Support

Visual forms support all DocSpring field types:

Text fields
Number fields
Date fields
Checkboxes
Radio buttons
Select dropdowns
Signatures and initials (see Signature fields)
Images
Combined fields

Styling

The visual form can be styled by targeting the following CSS classes:

.dsp-formWrapper - Main form container
.dsp-fieldWrapper - Field container
.dsp-button - Buttons
.dsp-primaryButton - Primary buttons
.dsp-headerWrapper - Form header
.dsp-footerWrapper - Form footer

Browser Compatibility

The visual forms library supports all modern browsers:

Chrome 60+
Firefox 55+
Safari 11+
Edge 79+

Older versions of Internet Explorer are not supported.