Introduction

When you use a Paperform form's direct link, such as example.paperform.co, the entire page is the form and only the form.

However, there are times when you might want the form to appear somewhere else, such as on your own website as a standalone page, inline with other content, or as a popup within the same page. In these cases, you may embed your form.

We'll cover the various methods, attributes, and things to note for embedded forms.

How It Works

  1. From the form editor, go to Share → Embed.

    Screenshot of the Embed option from the Share drop-down menu

  2. Choose from the available methods:

    • Inline
    • Full screen
    • Popup
  3. Copy the provided code (HTML, JavaScript) for the option you want to use.

  4. Go to the editor or HTML source where you want the form to appear and paste the code.

  5. Save and refresh the page to see your embedded form.

Typically, places where you want to include the embed code on other services are called code blocks or similar. You'll want to avoid putting any non-script elements in a header or footer as these places won't display things like div, a, or button on your page correctly.

Can’t use JavaScript? Use the iFrame fallback method.

Embedding methods

Inline

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.

Full screen

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.

Special Attributes

Attribute reference

  • 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.

Using the right embed code version

Updating your embed code

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.

Gotchas

Using `scroll-offset` when necessary

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.

Refreshing the page or viewing your live site

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.

iFrames

  • 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.