Embedded Visual Forms

This guide walks through implementing visual forms for PDF generation without the compliance features of data requests. For conceptual documentation about visual forms, see the Visual Forms documentation.

Implementation Steps

1. Prepare Your Template

First, ensure your PDF template is configured for visual forms:

1. Upload your PDF to DocSpring
2. Add form fields using the Template Editor
3. Configure template settings:
   • Set “Online Form Privacy” to “Public” (required, so that unauthenticated users can load the form)
   • Set submission privacy (Public recommended)
   • Configure redirect URL (optional)
   • Set up field defaults and validation

Template Editor Guide Learn how to create and configure PDF templates

2. Include the JavaScript Library

Add the visual forms stylesheet and library to your webpage:

Include visual forms library

<link
rel="stylesheet"
href="https://cdn.docspring.com/visual_form.v2.9.0.css"
/>
<script
  type="text/javascript"
  src="https://cdn.docspring.com/visual_form.v2.9.0.js"
></script>

Note

Enterprise deployments can load these assets from the local DocSpring domain instead of the CDN: https://docspring.yourcompany.com/assets/embed/visual_form.css and https://docspring.yourcompany.com/assets/embed/visual_form.js.

3. Initialize the Form

Add a container element, then create a visual form with your template ID. DocSpring.createVisualForm(selector, options) renders the form inline into the element that matches the selector. Visual forms do not open as a modal overlay.

Basic initialization

<div class="dsp-form"></div>

<script>
  DocSpring.createVisualForm('.dsp-form', {
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>

If your account is in the EU region, also pass region: 'EU'.

4. Pre-fill Form Data (Optional)

You can pre-populate form fields with default or static data:

Pre-filled form data

DocSpring.createVisualForm('.dsp-form', {
  templateId: 'YOUR_TEMPLATE_ID',

  // Default values (user can modify)
  defaultFormData: {
    customer: {
      name: 'John Smith',
      email: '[email protected]'
    },
    date: '2024-01-15'
  },

  // Static values (user cannot modify)
  staticFormData: {
    company_name: 'Acme Corporation',
    invoice_number: 'INV-2024-001'
  }

})

Note

Form data must match your template’s JSON schema structure. Use nested objects for grouped fields.

5. Handle Form Events

Add callbacks to respond to form events:

Event callbacks

DocSpring.createVisualForm('.dsp-form', {
  templateId: 'YOUR_TEMPLATE_ID',

  // Form is ready
  onLoad: function() {
    console.log('Form loaded');
  },

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

  // Form submission
  onSubmit: function(formData) {
    console.log('Form submitted:', formData);
    // Send data to your server if needed
  },

  // PDF generation
  onProcessed: function(data) {
    console.log('PDF ready:', data.downloadURL);
    // Custom handling (analytics, notifications, etc.)
  },

  // Error handling
  onError: function(error) {
    console.error('Form error:', error);
    alert('There was an error processing your form.');
  }

})

6. Customize the Experience

Visual forms offer extensive customization options:

Customization options

DocSpring.createVisualForm('.dsp-form', {
  templateId: 'YOUR_TEMPLATE_ID',

  // UI Options
  focusFirstFieldOnLoad: true,
  showSignatureModalOnFocus: true,
  downloadButtonLabel: 'Get My Document',

  // Skip terms of service
  skipAgreeToTermsOfService: true,

  // Redirect after the submission is saved
  // (or after the PDF is processed, if Submission Privacy is "Public")
  redirectURL: 'https://yoursite.com/thank-you'

})

Note

Header title and message options such as pdfProcessingTitle and completedTitle, and footerHTML, only work for data requests. Visual forms ignore them.

7. Style the Form (Optional)

Apply custom CSS to match your brand:

Custom styling

.dsp-form {
  font-family: 'Your Font', sans-serif;
}

.dsp-button.dsp-primaryButton {
background-color: #your-brand-color;
border-color: #your-brand-color;
}

.dsp-headerWrapper {
background-color: #f8f9fa;
border-bottom: 1px solid #dee2e6;
}

.dsp-fieldContainer.dsp-fieldFocussed {
box-shadow: 0 0 0 3px rgba(your-color, 0.1);
}

8. Handle Field Overrides (Advanced)

Dynamically modify field properties:

Field overrides

DocSpring.createVisualForm('.dsp-form', {
  templateId: 'YOUR_TEMPLATE_ID',

  fieldOverrides: {
    // Hide sensitive fields
    ssn: { hidden: true },

    // Change field styling
    signature: {
      backgroundColor: 'FFFEF0'
    },

    // Make fields required
    email: { required: true }
  }

})

Troubleshooting

Common Issues

Form doesn’t load

• Check template ID is correct
• Check that the template’s “Online Form Privacy” setting is “Public”
• Check browser console for errors

Fields don’t appear

• Verify template has form fields and has been saved successfully
• Check if fields are hidden by overrides
• Make sure you are using the right template version - you may need to publish a new version.

PDF doesn’t generate

• Check API logs for validation errors

Next Steps

Visual Forms JavaScript API Reference Complete API reference with all options and callbacks

Visual Forms Documentation Learn about visual forms and how they work

Data Requests Guide When you need legally binding signatures with compliance

Visual Forms Changelog Changelog entries for the Visual Forms JavaScript library