Visual Forms JS Library

Open in Claude Open in ChatGPT

This client-side JavaScript library allows you to embed a visual form on your own website to fill out PDF templates and generate PDFs.

Embedded Visual Forms GuideLearn how to embed our visual forms on your website

You can also get these release notes by email.

Changelog

2.22.0 Latest

Released on Nov 4, 2026

Signatures come only from signature requests, which record who signed and when. In a form with a signature or initials field, the signature pad works in test mode, with a warning at the top of the form. A live form says at the top that it can’t be signed as soon as it loads: its signature fields say “Test mode only” and don’t open, and it can’t be submitted. To print an image or a name on the PDF, use an Image or Text field. See Signature fields.
The redirect URL can have variables after its ? or #, such as ?name={{ data.first_name }}, which the form fills in with what the person submitted. See Variables.
The form sends its submission to your DocSpring app host, where it already loads the template, instead of the API host. The apiHost option is no longer used.

2.21.1

Released on Nov 4, 2026

A signing form opened by Data Requests JS 2.x no longer stops with “Please add … to your template’s Embed Domains” when your page, or the signer’s browser, sends no referrer, or when Embed Domains lists your site with a wildcard or a scheme. Our server already tells the browser which sites can show a live signature request, so the form checks your page’s address itself only for test signature requests.

2.21.0

Released on Nov 1, 2026

Signing pages can show your brand color on their buttons, with white or black text, whichever is easier to read. Set it on the Account page. Forms you embed on your own pages keep their colors.

2.20.0

Released on Nov 1, 2026

Check marks and shapes support the new condition types: Doesn’t equal, Doesn’t contain, Doesn’t start with, Doesn’t end with, Doesn’t match regex, Is blank and Isn’t blank. Like a Matches regex condition’s check, a click doesn’t select one: it shows whether the value matches.
Matches regex conditions use RE2 syntax and are matched with RE2’s JavaScript version, so the form and the PDF agree. A pattern RE2 doesn’t support (lookarounds, backreferences), or that the two versions would read differently (like \pL or \B), never matches. Any pattern matches quickly, however long the value. See Conditions.

2.19.2

Released on Oct 31, 2026

No changes to how forms look or work. The form shares code with the template editor, which now supports Word templates.

2.19.1

Released on Oct 30, 2026

The request that creates a submission sends the page’s CSRF token, like the requests that wait for its PDF. DocSpring’s API now checks the token when a browser that’s signed in to DocSpring calls it.

2.19.0

Released on Oct 29, 2026

Logs a deprecation warning in the browser console when the page passes the apiTokenId and apiTokenSecret options. They put an API token in the page, where anyone can read it and use your account. They still work: remove them, replace the token, and get private submissions’ PDFs on your server (Private Submissions and API Tokens).
Works on a page whose Content-Security-Policy doesn’t allow inline styles (no 'unsafe-inline' in style-src). The tooltips’ CSS is now in the form’s stylesheet, and the dropdowns and the signature font picker no longer add <style> elements. See Content Security Policy.
A form with a signature field now loads in a container without the dsp-form class, whatever selector you pass to createVisualForm. Earlier versions stopped with “No elements were found for selector .dsp-form”.

2.18.2

Released on Oct 27, 2026

Text is a little darker, for better contrast, and borders are a slightly different grey. Buttons and field highlights keep their colors.
New icons for closing the signature window and resetting a field.
An inline signature pad shows a signature that is already in the form’s data (from a saved draft, for example), instead of an empty pad.

2.18.1

Released on Oct 27, 2026

Conditional logic now runs on the same rule engine as web forms and PDF generation, so a rule shows, hides and requires the same fields everywhere.
A rule that targets a group or a list by its name (which the API allows) now shows and hides every field in it, and a group or list that a rule requires needs a value in at least one of its fields. Earlier versions ignored these rules.
A rule that also targets a field inside a list’s rows, which isn’t supported yet, now still shows and hides its other fields, as the PDF does.
A group whose fields are all numbered (phones/0, phones/1) is a list, as in the API’s schema: a rule can target the list, but not the fields in it.
Number conditions read only decimal numbers, such as 5, -1.5 or 1e3, as numbers: a field’s value 0x10 isn’t 16. A Greater or Less rule with a bound like 0x10 is ignored, In Range treats it as an open bound, and Equals compares it as text.

2.18.0

Released on Oct 26, 2026

A template with a static Number field that has a default or a formula can be submitted. The form sent the field’s value, which the template’s JSON schema doesn’t allow, so the submission failed. The value is still shown, and calculated again when the PDF is generated.
The form ignores values for a field that is static in the template, in defaultFormData, staticFormData or a field override of a static Number field’s default, and shows the template’s value, which the PDF prints. The API rejected a submission with them. A template that allows additional properties accepts them, so the form keeps and submits them, as before. The onSubmit callback still gets every static field’s value.
Image fields with a default value no longer make the submission fail. The default isn’t sent: the PDF shows it when the field is optional and left empty.
Check marks and shapes match their Condition as the PDF does. Starts With, Ends With and Regex conditions no longer stop the form from loading, and Number conditions are applied. A Regex is matched as Ruby matches it, apart from some Ruby-only syntax that the form doesn’t support. A String check mark or shape whose Equals condition is empty is selected only when its value is empty, as the PDF draws it. It was always shown selected.
Clicking a selected optional check mark or shape clears it, also when a longer value selects it (Starts With, Ends With or Contains). A Regex check mark only shows whether the value matches: clicking it doesn’t change the value.
Images passed in defaultFormData or staticFormData, or sent with the submission, count as filled in and are shown. So do signatures and initials on a visual form. One the form can’t preview (a URL or an uploaded image ID) shows “Image added”, “Signed” or “Initialed”. A typed signature with a blank name doesn’t count as signed.
A prefilled image that the field only shows can’t be replaced: clicking it no longer opens the file picker.
In a signature request, only the signer can sign: the form ignores signatures and initials in defaultFormData and staticFormData, and a signature field the request asks for starts empty. A signature the submission already has for another field is shown read-only, and no longer stops the signer from finishing.
A field whose options were removed in the template editor shows a text input instead of an empty drop-down.
A static field with options, or a field whose value is shown read-only, shows its value instead of a drop-down. A required drop-down can be changed but no longer cleared.
An option list with spaces after its commas (Yes, No) no longer rejects the options after the first one.
Fields for each item of a list (named like items/0/code) are checked item by item. A required one no longer stops the form from being submitted when every item is filled in, and max length, number limits, email and option checks apply to each item. An empty item before a filled one is sent as an empty item instead of null, which the API rejected. In a signature request, a field list that names a list’s field with ~ (items/~/code) asks for every item, and one that names an item (items/0/code) asks for only that item.
A Number field named length is submitted with the form.
Shows the dates in fields named @@signature_requests/N/completed_at and viewed_at, the new name for @@data_requests/N/... (which still works).
A completed_at or viewed_at field for another signer shows the dates of the signature request with index N, as the PDF does (see special field names). When no signature request had that index, it showed the next signer’s dates.
The internal error for a form opened without its signature request options names the missing options, without their values.
onError gets { error, message } when the PDF couldn’t be generated (processing_failed), and once when it takes more than a minute (processing_timeout) while the form keeps waiting. It got nothing before, every second after the first minute. A failed save still passes the request’s error.
Waiting for the PDF carries on after a failed status check, and stops after five in a row. It stopped at the first.

Signing forms (signature requests):

A signer can only fill in the fields the signature request asks them to fill in. Every other field is read-only and shows what the PDF will print, and isn’t shown when there’s nothing to print. DocSpring only saves the signer’s own fields.
setField(), defaultFormData and staticFormData only fill in the signer’s own fields. setField() can’t fill in a signature or initials field: only the signer signs.
submitForm() shows the I Agree step, as the Continue button does (or the fields that still need a value). The signer agrees to submit.
Opened by Signature Requests JS 3.0.0, the form ignores setField(), submitForm(), defaultFormData, staticFormData and domainVerification, and sends onError an error code and a message for every error.
The form only takes messages from the page that opened it, takes the page’s options once, and only the options Signature Requests JS (or Data Requests JS) sends.
A read-only image or signature field no longer opens the file picker or the inline signature pad.
A list field or multiline field that the signature request asks for is shown even when it’s empty, and static and combined fields are shown.
An image or signature that the PDF prints from a URL shows the copy that DocSpring downloaded when the submission was created, which the PDF prints, and Loading image… until it’s downloaded.

In visual forms and signing forms:

A combined field shows what the PDF prints, including other signers’ values, with each value formatted as the PDF prints it (dates in their date format, numbers with their decimal places, check boxes as their true or false text).

2.17.1

Released on Oct 22, 2026

Internal changes to how page sizes are read, shared with the template editor. Forms look and behave the same.

2.17.0

Released on Oct 21, 2026

Shows the new triangle and polygon shapes. Older versions show them as rectangles.
A shape that isn’t selected is shown faded, as an unselected check mark is, so people can see which shapes they picked. The PDF only draws the selected ones.

2.16.0

Released on Oct 20, 2026

Added the allowSkippingOptionalFields option and support for the template’s Show Continue Once Required Fields Are Filled In setting, so the Continue button can appear as soon as every required field is filled in. Values passed in defaultFormData now count as filled in.
Required fields are highlighted in the template’s required field color, when it has one.
A field’s background color is shown at the field’s opacity, as in the PDF. Translucent static shapes are no longer drawn fainter than in the PDF.
Text fields stop accepting characters at the field’s maximum length. A value that is already too long (for example from defaultFormData) shows an error on the field instead of failing when the form is submitted.
Unchecking an optional radio button, or clearing an optional number, select or date field, no longer makes the submission fail. onFieldChange gets the value that is stored: null, or on accounts that use template JSON schema version 1, '' or undefined (the value is left out), depending on the field’s type. On schema version 1, a default or prefilled value then comes back (see Clearing Optional Fields).
A field keeps showing its default value, defaultFormData value or formula result while the user is in it, instead of going blank, and the user edits it like any input. Moving to a field with Tab, Shift+Tab or the Next button selects its text, so typing replaces it.
A cleared optional text, email or URL field stays empty, instead of its default value coming back. A cleared required field still gets its default back when the user leaves it.
A text, number, email or URL field the user has changed shows a ↺ button, which puts back what the field showed before: its default value, its defaultFormData value, its value from the submission, or what its formula calculates now. onFieldChange gets undefined (the user’s value is removed), or the submission’s value in a data request.
Shift+Tab moves to the previous field, the arrow keys move between the options of a radio button group, and Space selects a radio button like a click. An inline form only takes these keys while the user is in it, so it no longer takes the Tab key from the rest of your page. See Keyboard.
When DocSpring rejects the submitted data, the form names each field and says what is wrong with it, instead of asking the user to refresh the page. Number fields’ minimum and maximum values are checked before the form is submitted.

2.15.0

Released on Oct 18, 2026

New global functions: DocSpring.getFormData() returns the values entered in the form, and DocSpring.setFormData(data) replaces them. Fields that data leaves out go back to their default values. Static fields, and fields set with staticFormData, keep their values.
New metadata option: an object that is saved with the submission.
The test option can be a function, called when the form is submitted.
A form inside a hidden element no longer handles key presses or measures its fields. After you show it, send a window resize event so it measures them.
The Tab key moves to the form’s next field only while the focus is in the form (or nowhere on the page), so it can still reach the rest of the page.

2.12.0

Released on Oct 18, 2026

onProcessed is now called when the form redirects to a redirect URL. The redirect follows one second later, so the callback has time to finish.
The string options for the header titles and messages (such as pdfProcessingTitle and completedTitle) and footerHTML now work in embedded visual forms. Before, only data requests used them.

2.11.0

Released on Oct 18, 2026

Date fields show the date the PDF will print. Dates sent as NN/NN/YYYY are read day first, or in the order of the template’s date format when the template’s Parse Dates Using the Template’s Date Format setting is on. Before, the form read them month first and could show a different date from the PDF.
The date picker shows dates in the template’s default date format when the field has no format of its own, as the PDF does.
Dates sent as YYYY-MM-DD no longer show as the day before in time zones behind UTC.
Static date fields show their default value as written, as the PDF prints it. Before, the form reformatted it as a date.

2.10.1

Released on Oct 16, 2026

In a data request, the form no longer sends a field’s default value when the submission already has a value for that field (from the API or an earlier signer). The signer saw the existing value, but the generated PDF could show the default value instead.

2.10.0

Released on Oct 14, 2026

Added the Decline button that Data Requests JS 2.4.0 shows in the form header, so a signer can decline to sign.

2.9.1

Released on Oct 14, 2026

Static check marks are now always shown at full opacity, the same as in the PDF. Their condition no longer applies (except for Number fields), and Hidden turns one off.

2.9.0

Released on Oct 13, 2026

Formulas are calculated the same way as in the generated PDF, so the form shows the values that will be printed.
A formula stays blank until one of the fields it uses has a value. Default values don’t count.
If a formula can’t be calculated with the values entered (for example, when it divides by zero), the form shows the problem on the field and can’t be submitted until the values change. A problem with a formula that the form doesn’t ask for is shown at the top of the form.
In a data request with more than one signer, formulas are calculated with every signer’s values.
Formulas can use fields in a list of objects, and a field in a list can have a formula that is calculated for each row.
Number fields show the values passed in defaultFormData or already saved on the submission, instead of their default value or formula.

2.8.3

Released on Oct 7, 2026

The library no longer uses your page’s Sentry SDK when you embed a form directly on your site. If your site used an older Sentry SDK (version 7 or earlier), embedding a visual form could stop your own Sentry error reporting.
DocSpring’s own error reporting only runs on DocSpring-hosted pages, and never includes the data entered into the form.

2.8.2

Released on Oct 7, 2026

Check fields now always display their check character as plain text.
Combined field tooltips now display the field title as plain text.
Updated DOMPurify, which sanitizes field labels and form messages, to 3.4.16.

2.8.1

Released on Aug 28, 2026

Removed the AU region option. The AU region has been shut down, so region now accepts US or EU.

2.8.0

Released on Aug 13, 2026

Added support for conditional logic: fields can be shown, hidden, or conditionally required based on the value or presence of other fields.

2.7.7

Released on Jul 8, 2026

Fixed the page crashing or reloading when pinch-zooming forms on iOS (mobile Safari and Chrome). The form no longer creates a GPU compositing layer for every field, which was exhausting the browser’s memory limit during zooming.
Fixed date fields using a larger font size than other fields on mobile devices, and vertically centered the date text in the field.
Fixed the required field star being positioned too far away from checkboxes on mobile devices.

2.7.6

Released on Jun 25, 2026

Added region, host, appHost, and apiHost options for configuring US, EU, AU, and enterprise deployments.
Fixed template image, template data, submission, and polling URLs so they all use the same configured host settings.

2.7.5

Released on Jun 24, 2026

Fixed the signature modal drifting off-screen during pinch-to-zoom on mobile devices. The modal now repositions itself whenever the visual viewport changes.
Fixed the “Please zoom out” message never appearing when the form is embedded in an iframe (it now checks the parent page’s zoom level).

2.7.4

Released on May 4, 2026

Updated internal template metadata handling for incremental PDF processing

2.7.3

Released on Mar 10, 2026

Improved dark mode styling across embedded visual forms (header, footer, and form fields)
Updated signature modal colors and contrast for better readability

2.7.2

Released on Jan 22, 2026

Added support for initials fields in visual forms / data requests

2.7.1

Released on Jul 10, 2025

Updated JavaScript build process and dependencies

2.7.0

Released on Jan 31, 2025

Added support for template versioning. You can now specify a template version when showing the form.

2.6.5

Released on Dec 4, 2024

Fixed issue with formula fields that couldn’t operate on individual fields in arrays.

2.6.4

Released on Oct 17, 2024

Fixed issues with clicking “Next” to select the next field. We will now show the “all fields completed” message once the user has clicked through all fields in the form (including optional fields.) We also show the completed message if all required fields are filled out but no field is currently selected.

2.6.3

Released on Jul 19, 2024

Improved signature field layout on mobile devices and tablets
Fixed some issues with zooming and scrolling

2.6.1

Released on Dec 19, 2023

Fix drop down menu not showing scrollbar

2.6.0

Released on Dec 19, 2023

Add support for formula calculations

2.5.10

Released on Aug 25, 2023

Add test flag to enable test submissions through the embedded form

2.5.9

Released on Aug 18, 2023

Updated styling, upgraded library for select elements

2.5.7

Released on Aug 2, 2023

Added DocSpring.setField(name_or_id, value) function to set the value of a field.
Updated DocSpring.focusField(name_or_id) function to accept either a field name or a numeric ID.

2.5.6

Released on Jun 8, 2023

Fixed issue with signature modal when phone screen is rotated

2.5.5

Released on Jun 16, 2022

Added “shrink to fit” support for multi-line fields using the Truncate: “Shrink to Fit” option. The font size will now decrease to fit all of the text in the field. (Please note that this is an approximation. The text may be slightly different on the generated PDF.)

2.5.4

Released on Mar 25, 2022

Dates provided as static form data are now formatted correctly using the specified date format

2.5.3

Released on Mar 10, 2022

Added the Lovtony Script font as an option for signature fields

2.5.2

Released on Apr 6, 2021

Added a footerHTML option that allows you to configure content for a custom footer.

2.5.1

Released on Mar 4, 2021

Added support for shrink-to-fit on multi-line fields

2.5.0

Released on Mar 2, 2021

Added support for background color, opacity, text alignment for fields with static data
Added fieldOverrides option for visual forms, so that you can override field properties (e.g. required, hidden)
Added documentation for DocSpring.***() functions to control the form UI:
- DocSpring.clearForm()
- DocSpring.submitForm()
- DocSpring.focusNextField()
- DocSpring.focusField(id)
Added a “Preview Mode” that allows you to use the visual forms as a read-only preview for static data.
- previewMode: true
- previewModeButtonLabel: "Agree"
- onPreviewModeButtonClicked: function () { ... }

2.4.2

Released on Jan 12, 2021

Added support for image uploads (click to select an image file)

2.4.1

Released on Dec 15, 2020

Fixed the “terms of service” link so that it opens in a new window. (Also removed the X-Frame-Options header from this page, so that it is possible to render inside an embedded iframe.)

2.4.0

Released on Nov 24, 2020

Fixed signature modal layout on various tablet and mobile screen sizes

2.3.12

Released on Oct 28, 2020

Added support for the “Invert Boolean Condition” field option, where a checkbox will show as checked when the value is false.
Allow a checkbox to be unchecked if it is part of an optional “radio group” with string conditions.

2.3.11

Released on Oct 7, 2020

Added a new skipAgreeToTermsOfService option for visual forms. Setting skipAgreeToTermsOfService: true will skip the “Agree to Terms” step, so clicking the “Continue” button will immediately submit the data and generate a PDF. NOTE: This option is only available for Visual Forms, and it is not available for Data Requests.

2.3.10

Released on Sep 27, 2020

Fixed issue where fields could be horizontally shifted on Windows and Linux when the form was rendered with a vertical scrollbar.

2.3.9

Released on Sep 24, 2020

Fixed vertical alignment for text in select dropdowns. Text should now be vertically centered properly.

2.3.8

Released on Sep 9, 2020

For Data Request users: Added support for all field_overrides (from the Generate PDF API requests), so that field options can be configured dynamically for each data request.

2.3.7

Released on Aug 7, 2020

Added a new signatureLegalDisclaimerMessage string option, added formData parameter for agreeToTermsTitle and agreeToTermsMessage string options. (Only used with Data Requests.)

2.3.6

Released on Aug 4, 2020

Added agreeToTermsTitle and agreeToTermsMessage string options. (Only used with Data Requests.)

2.3.5

Released on Jun 18, 2020

Added support for multiline fields so that users can enter text with multiple lines. Also added support for the “Number of Lines” option, which vertically divides the field into a fixed number of lines.

2.3.4

Released on Jun 6, 2020

Fixed bug with field_overrides option for submissions with data requests. If a field override is provided, fields will now be correctly marked as required or optional in visual forms.

2.3.3

Released on Jun 4, 2020

Fixed a bug where select dropdown menus were hidden behind other fields.

2.3.2

Released on Apr 28, 2020

Fixed error when opening the signature font drop-down and pressing backspace
Added ‘Type Signature’ heading above the name input when typing a signature

2.3.1

Released on Apr 27, 2020

Made some internal changes for better error handling and debugging

2.3.0

Released on Apr 25, 2020

Fixed crash for any browsers configured to block all cookies. Before this fix, the loading spinner would sometimes get stuck and the signing iframe would fail to load.

2.2.1

Released on Apr 7, 2020

Increased legibility of tabs heading in the signature modal.

2.2.0

Released on Apr 2, 2020

Fixed bug where static form data could not be overridden after clearing a field

2.1.0

Released on Mar 1, 2020

Show all previous signatures and date fields for multiple data requests

2.0.3

Released on Jan 17, 2020

Allow past dates to be selected in date pickers

2.0.1

Released on Nov 25, 2019

Improve date picker styles
Improve text rendering in fields

2.0.0

Released on May 20, 2019

Renamed FormAPI to DocSpring