Embedding Guide

A form embedded inline can be used within an existing page on your website, resting above, below, or between other content. This method lets you insert a form on your page as if you were inserting another paragraph and is the most common option.

If you want your form to look like it does on Paperform where it takes up the entire screen but want to display it on your own website instead of directing respondents to a Paperform URL, the full screen method is perfect.

A form doesn't always have to be visible on a page such as with the inline or full screen methods. A common approach is to have a form "pop up" on the page when an element, such as a button, is clicked.

You can use any element to respond to the popup so long as you include data-paperform-id="form-id" and data-popup-button="1" in the element's attributes.

Programmatic popup

To have greater control over how and when the popup form appears, you can programmatically call the form by

• including the script: <script src="https://paperform.co/__embed.min.js"></script>
• calling the popup function: Paperform.popup('form-id')

For example, this could let you only have the form pop up under a combination of factors, after a certain delay, or something else.

A working example of this in action looks something like

<script>
  document.querySelector('#element-id').addEventListener('click', function() {
    Paperform.popup('my-form-name');
  });
</script>

where #element-id is the ID of the target element.

Programmatic Embed Special Attributes

When using our programmatic embedding method, you can use the special attributes listed below via a second argument in your function.

For example:

<script>
  document.querySelector('#element-id').addEventListener('click', function() {
    Paperform.popup('my-form-name', {
        prefillInherit: "1", // See reference for `prefill-inherit`
        prefill: "key=value"
    });
  });
</script>

• prefill="key=value&key2=value"

  To use pre-filling directly through the element, you may pass hardcode values. For example, you might pre-fill UTM parameters here instead of placing them in the URL's query string.

• prefill-inherit

  To pre-fill a form by using the query string of the page it's embedded on, you may pre-fill by inheritance, setting this attribute on the element you're using to embed the form. This lets you dynamically pre-fill the form based on the current query string.

• scroll-offset="number"

  When changing pages on an inline, embedded form, the page is automatically scrolled to the top of the form.

  However, if the page the form is embedded on has a fixed header or the form consistently sits lower on the page than the top, page changes may cause the scroll position to be lower than expected and may cause confusion for respondents as to where the form went.

  Setting the scroll-offset to a number of pixels offsets what is considered the "top" and enables page changes to more reliably alter the scroll position to where it needs to be.

  For example, if there is a fixed header of 100px, you would want to use embed code that looks like

  <div scroll-offset="100" data-paperform-id="form-id"><div>
  

• no-scroll="1"

  When changing pages on an inline, embedded form, the page is automatically scrolled to the top of the form.

  If you want to disable this behavior entirely, you can set no-scroll equal to "1".

• spinner

  Use this to include a spinner (loading indicator) while the form is loading.

• lazy

  Delay loading an inline, embedded form until the form has scrolled into view on the screen.

• height="600px"

  This attribute applies to guided mode only.

  The height of the embedded form may be restricted to a specific height. The value can be any valid CSS unit (px, %, em, rem, vw, vh, ...).

  This is commonly used to reduce the amount of space a guided mode form takes, including the spacing between the centered form content and any buttons.

  The height may never be larger than the viewport.

• border

  Show a border around an inline, embedded form.

• border-color="black"

  Change the color of the border around an inline, embedded form. The color value can be any valid CSS color. If the border attribute is not present, this attribute will not do anything.

• onsubmit="functionName"

  Call functionName with the submission data on submission. The function must be defined on the window to be called.

  Review the draft API documentation for more information.

• onpagechange="functionName"

  Call functionName when the page changes in a form, including the currentPage and totalPages in each response.

  Review the draft API documentation for more information.

• title="This is a title"

  Set the title of the embedded form's iframe.

  This can be useful for accessibility purposes.

In Paperform V3, we released an updated version of the embed code to support features like Guided Mode, spinners, and lazy loading.

To update your embeds, you can just replace the URL of the script from https://paperform.co/__embed to https://paperform.co/__embed.min.js.

Example of all attributes being utilized

<div 
  prefill="name=Danny"
  prefill-inherit 
  scroll-offset="100"
  no-scroll="1"
  spinner
  lazy
  height="600px"
  border
  border-color="black"
  onsubmit="submissionHandler"
  onpagechange="pageChangeHandler"
  title="My form's title"
  data-paperform-id="form-id"
></div>

Note: The above HTML may not work as is.

Not all attributes are compatible with each other (e.g. scroll-offset and no-scroll) or they may require specific configuration (e.g. height requires guided mode).

The formatting of one attribute per line is for readability; you are not required to format your HTML exactly like this.

Recall from the above attribute reference that inline, embedded forms that are positioned lower than the top of the page — which is usually the case — may not scroll as expected on page changes. Using scroll-offset alleviates this issue when set correctly.

Some website builders won't display the form in the editor or preview views of the platform. You may need to either refresh the page or possibly view the live version of your page in order to see the form displayed.

Inline
By targeting the div width and div height within the page your inline form appears on, you can change the size of the form with Custom CSS. If using the iFrame fallback method, you can change the size within the HTML snippet.

Pop-up
You can change the size within the page your form pop-up appears on. We have a snippet of example CSS to get you started.

• Some website builders don't play nice with an iframe and may cause unexpected issues.
• Certain configurations (e.g. security policies, parental controls) can block an iframe.
• You can't modify the content in an iframe from the page you're embedding it within.
• If a website builder wraps our iframe in their own iframe, you'll be unable to use prefill-inherit successfully since you'd be inheriting from their iframe instead of the page you mean to embed on.

If using the fallback method, a few additional points apply:

• Cannot be dynamically resized as the form length changes.
• Cannot control the scroll position of the page it's embedded on.
• Do not support PayPal payments.