Visual Forms JavaScript API

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 data requests, but it provides more flexibility and has many options for customization and styling.

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

Visual Forms Changelog Changelog 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

Note

You can alternatively pass templateData with cached template data instead of templateId to make the page load faster.

Configuration Options

Option	Type	Default	Description
templateVersion	string	null	The template version to show and submit, e.g. "1.2.3"
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
redirectURL	string	null	Redirect to this URL after submitting the form
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	false	Create a test submission instead of a live submission
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
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	Override the API host used for submission and polling requests

Region and Custom Host

Use region when your account is in the EU region:

Regional visual form

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

For single-domain enterprise deployments, use host:

Enterprise host

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

For split-domain deployments, use appHost and apiHost. 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.

Caution

These options are only used by Data Requests, where the signing form runs inside an iframe. An embedded visual form ignores them, so it shows the default titles and messages and no custom footer.

Option	Function Arguments	Description
pdfProcessingTitle	template (object)	Title when PDF is being processed
pdfProcessingMessage	template (object)	Message when PDF is being processed
waitingForDataRequestsTitle	remainingDataRequestsCount (number), template (object)	Title when waiting for data requests
waitingForDataRequestsMessage	remainingDataRequestsCount (number), template (object)	Message when waiting for data requests
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. Not called if 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.returnToForm()	-	Return to the form after it has been submitted

Examples

Basic Usage

Basic visual form

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

With Pre-filled Data

Pre-filled form 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'
  }

})

Custom Configuration

Advanced 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 redirects instead, and onProcessed is not called.

Field Overrides

Field property overrides

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

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

})

Preview Mode

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
  }

})

Field Types Support

Visual forms support all DocSpring field types:

• Text fields
• Number fields
• Date fields
• Checkboxes
• Radio buttons
• Select dropdowns
• Signatures
• 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.