# Embedded Web Forms

> Step-by-step guide to embed DocSpring web forms on your website

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

You can embed DocSpring web forms on your own website, allowing users to fill out forms and generate PDFs without leaving your site. Users can be redirected to a different page after submitting the form, or you can run custom code in JavaScript callbacks.

> **Tip:** Before you start, make sure you’ve configured your template’s privacy settings to allow public access.

[Configure Template Privacy Settings](https://docspring.com/docs/forms/web-forms/#configure-template-privacy-settings): Learn how to set up your template for public access

## Quick Start

To embed a form on your website, copy the following code and replace `TEMPLATE_ID` with your actual template ID:

`Basic embedded form`

```html
<link
rel="stylesheet"
href="https://cdn.docspring.com/embed/web_form.v3.2.2.css"
/>
<script src="https://cdn.docspring.com/embed/web_form.v3.2.2.js"></script>


<div class="dsp-form"></div>
<script>DocSpring.createWebForm(".dsp-form", "TEMPLATE_ID");</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/web_form.css` and `https://docspring.yourcompany.com/assets/embed/web_form.js`.

> **Note:** If your account is in the EU region, set `DocSpring.appHost` before you call `DocSpring.createWebForm()`: `DocSpring.appHost = "app-eu.docspring.com";`

The form is drawn inside the `<div class="dsp-form"></div>` element.

> **Note:** This guide uses Web Forms JS 3.x. If your page calls `DocSpring.createSimpleForm()`, it loads 2.x, which keeps working. To move it to 3.x, see [Upgrading from 2.x](https://docspring.com/docs/changelogs/web-forms-js/#upgrading-from-2x).

## Examples

### Basic Form with Options

Here’s an example that demonstrates common options:

`Form with common options`

```html
<div class="dsp-form"></div>
<script>
  DocSpring.createWebForm('.dsp-form', 'tpl_123456', {
    // Set default values for form fields
    defaultData: {
      name: 'John Smith',
      email: 'john@example.com'
    },


    // Add metadata to the submission
    metadata: {
      userId: '12345',
      source: 'website'
    },


    // Customize button labels
    submitButtonLabel: 'Generate PDF',
    clearButtonLabel: 'Reset Form',


    // Redirect after submission
    redirectURL: 'https://example.com/thank-you'
  })


</script>
```

### Form with Callbacks

Use callbacks to hook into form events:

`Form with event callbacks`

```html
<div class="dsp-form"></div>
<script>
  DocSpring.createWebForm('.dsp-form', 'tpl_123456', {
    // Called when form is submitted
    onSubmit: function(formData) {
      console.log('Form submitted with data:', formData);
      // Track analytics event
      gtag('event', 'form_submit', {
        'event_category': 'engagement',
        'event_label': 'pdf_generation'
      });
    },


    // Called when form is saved
    onSave: function(submission) {
      console.log('Submission saved with ID:', submission.id);
    },


    // Called when PDF is ready (if Submission Privacy is "Public")
    onProcessed: function(submission) {
      console.log('PDF ready! Download URL:', submission.download_url);
      // Show custom success message
      alert('Your PDF is ready to download!');
    },


    // Called on error
    onError: function(error) {
      // The form also shows the message above its buttons
      console.error(error.error, error.message);
    }
  })


</script>
```

### Advanced Example

For a complete example that uses all available options and callbacks:

* [View HTML source](https://docspring.com/embed_web_form_example?view_source=true)
* [See the live form](https://docspring.com/embed_web_form_example)

## Handling Form Submission

### Redirect After Submission

You can redirect users to a thank you page or another URL after they submit the form. The redirect URL can be configured in two ways:

1. **In the template settings** - Set a default redirect URL for all forms
2. **In the JavaScript options** - Override the default for specific forms

The submission details will be appended to the redirect URL as query parameters:

```plaintext
https://example.com/thank-you?submission_id=sub_123&template_name=My%20Template&template_version=latest&template_id=tpl_123
```

> **Note:** The redirect behavior depends on your template’s “Submission Privacy” setting:
>
> * **Private**: Redirects immediately after saving
> * **Public**: Waits for PDF processing before redirecting (unless `waitForPDF` is set to `false`)

### Custom Success Handling

Once the form is submitted, a success screen takes its place: a title, the template’s message, a **Download PDF** button when “Submission Privacy” is “Public”, and a **Fill out again** button. Set them in the template’s Forms settings, or with the `successTitle`, `successMessage` and `showFillAgainButton` options. See [Success screen](https://docspring.com/docs/forms/js-libraries/web-forms-js/#success-screen).

To show your own message instead, pass `showSuccessScreen: false`, which keeps the form on the page, and handle the submission in the `onSave` or `onProcessed` callback. Leave the template’s redirect URL setting blank: passing `redirectURL: null` does not override a redirect URL that is set on the template. `onProcessed` is only called when “Submission Privacy” is set to “Public”.

`Custom success handling`

```javascript
DocSpring.createWebForm(".dsp-form", "tpl_123456", {
  showSuccessScreen: false,
  onProcessed: function (submission) {
    // Hide the form
    document.querySelector(".dsp-form").style.display = "none";


    // Show your own message
    const successDiv = document.getElementById("success-message");
    successDiv.innerHTML = `
      <h2>Thank you</h2>
      <p>Your PDF has been generated.</p>
      <a href="${submission.download_url}" class="btn btn-primary">Download PDF</a>
    `;
    successDiv.style.display = "block";
  },
});
```

## Styling the Form

The form comes with its own styles, scoped to the `.dsp-web-form` element it draws inside your container. Change its colors, font and sizes with CSS custom properties:

`Custom form styles`

```css
.dsp-web-form {
  /* Your page's font is the default */
  --dsp-font-family: "Inter", sans-serif;
  --dsp-primary: #28a745;
  --dsp-primary-hover: #218838;
  --dsp-radius: 4px;
}


/* Center the form, at most 600px wide */
.dsp-form {
  max-width: 600px;
  margin: 0 auto;
}
```

You can pass the same values with the `theme` option, and show a dark theme with `darkMode: true` (or `"auto"` to follow the visitor’s system setting).

[Styling Web Forms](https://docspring.com/docs/forms/js-libraries/web-forms-js/#styling-web-forms): Every custom property, the dark theme and the form's classes

## Next Steps

[Web Forms JavaScript API Reference](https://docspring.com/docs/forms/js-libraries/web-forms-js/): Complete reference for all options and callbacks

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

[Web Forms Documentation](https://docspring.com/docs/forms/web-forms/): Learn about query parameters and advanced configuration
