# Embedded Visual Forms

> Step-by-step guide to embed visual PDF forms on your website

Source: https://docspring.com/docs/guides/embedded-forms/embedded-visual-forms/
All of DocSpring's documentation: https://docspring.com/docs/llms.txt

This guide walks through implementing visual forms for PDF generation without the compliance features of signature requests. For conceptual documentation about visual forms, see the [Visual Forms documentation](https://docspring.com/docs/forms/visual-forms/).

## 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](https://docspring.com/docs/template-editor/introduction/): 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`

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

> **Note:** [DocSpring Enterprise](https://docspring.com/docs/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`

```html
<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`

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


  // Default values (user can modify)
  defaultFormData: {
    customer: {
      name: 'John Smith',
      email: 'john@example.com'
    },
    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`

```javascript
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`

```javascript
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'


})
```

You can also change the titles and messages in the form header, and add a footer, with the [string options](https://docspring.com/docs/forms/js-libraries/visual-forms-js/#string-options) such as `pdfProcessingTitle`, `completedTitle` and `footerHTML` (version 2.12.0 or above).

### 7. Style the Form (Optional)

Apply custom CSS to match your brand:

`Custom styling`

```css
.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`

```javascript
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 }
  }


})
```

## Embed Domains

A form only loads on the sites in your template’s **Embed Domains** setting, on the **Embedding** tab of its [settings](https://docspring.com/docs/template-editor/settings/). A blank setting doesn’t restrict the form. The same setting lists where you embed your template editor and signature requests, so it needs all of those sites.

List the sites separated by commas, such as `forms.example.com, *.example.net, localhost:3000`. An entry without a port allows any port, and `*.example.net` allows every subdomain of `example.net`.

On any other site, the form shows a message naming the host to add, logs it to the browser console, and calls your `onError` callback with:

`onError argument`

```javascript
{
error: 'embed_domain_not_allowed',
message: 'Please add "www.example.com" to your template's Embed Domains on the settings page. ...'
}
```

While you develop, the `domainVerification: false` option turns the check off.

The check runs in the visitor’s browser, so it discourages reusing your form on other sites but can’t prevent it, and it doesn’t make the form private. To keep generated PDFs private, see [Private Submissions and API Tokens](https://docspring.com/docs/forms/visual-forms/#private-submissions-and-api-tokens).

## Troubleshooting

### Common Issues

**Form doesn’t load**

* Check template ID is correct
* Check that the template’s “Online Form Privacy” setting is “Public”
* If the template’s [Embed Domains](https://docspring.com/docs/guides/embedded-forms/embedded-visual-forms/#embed-domains) setting isn’t blank, check that it lists this site
* 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](https://docspring.com/docs/forms/js-libraries/visual-forms-js/): Complete API reference with all options and callbacks

[Visual Forms Documentation](https://docspring.com/docs/forms/visual-forms/): Learn about visual forms and how they work

[Embedded Signature Requests Guide](https://docspring.com/docs/guides/embedded-forms/embedded-signature-requests/): When you need legally binding signatures with compliance

[Visual Forms Changelog](https://docspring.com/docs/changelogs/visual-forms-js/): Changelog entries for the Visual Forms JavaScript library
