node package manager

@typeform/embed

Embed Build Status js-standard-style npm

Typeform/embed is the client-side script and a CommonJS module that allows you to integrate a typeform into your website easily.


If you are searching for a backend integration with the embed take a look into here.

In case that you are not comfotable with Front end Development you can use the code snippet that we provide in our platform

Getting Started

Installation

We recommend to use npm as your package manager, and also a build tool like webpack or browserify in order to use it.

npm install --save @typeform/embed

If you're not, you can still use it with our CDN:

<script src="https://embed.typeform.com/embed.js"></script>
<!-- this script exposes the API to `window.typeformEmbed` -->

Usage

// Using ES6 imports
import typeformEmbed from '@typeform/embed'
// or require
const typeformEmbed = require('@typeform/embed')

Types of Embed

Widget

Use a widget to embed a typeform inside any HTML element on your page

typeformEmbed.makeWidget(element, url, options)
  • element: the DOM element that the widget will be appended to

  • url: typeform's URL (like: https://admin.typeform.com/to/PlBzgL)

  • options: Object with the optional parameters:

    option description values default
    opacity You can make your typeform's background totally transparent, or opaque. (For example, to have a video as a background) Number 100
    buttonText The button text that aperas on mobile in order to open the typeform. String "Start"
    hideScrollbars Hide fixed scrollbars. Boolean false
    hideFooter Hide typeform footer, that appears showing the progress bar and the navigation buttons. Boolean false
    hideHeaders Hide typeform header, that appears when you have a Question group, or a long question that you need to scroll through to answer, like a Multiple Choice block. Boolean false

    #### Example:

    // Here we are getting an existing element on your HTML
    const embedElement = document.querySelector('.js-typeform-embed')
     
    typeformEmbed.makeWidget(
      embedElement,
      'https://admin.typeform.com/to/PlBzgL',
      {
        opacity: 55,
        buttonText: "Answer this!",
        hideScrollbars: true
      }
    )

Popup

Use a popup to embed the typeform in a modal window.

typeformEmbed.makePopup(url, options)
  • url: typeform's URL (like: https://admin.typeform.com/to/PlBzgL)

  • options: Object with the optional parameters:

    option description values default
    mode typeform Embed Popup modes
    The way of showing the embed
    String any of:
    "popup"
    "drawer_left"
    "drawer_right"
    "popup"
    autoOpen Your typeform will launch as soon as your web page is opened Boolean false
    autoClose The popup will close after the user submits the response with a delay. That's a PRO+ feature. Number (miliseconds) -
    hideScrollbars Hide fixed scrollbars. Boolean false
    hideFooter Hide typeform footer, that appears showing the progress bar and the navigation buttons. Boolean false
    hideHeaders Hide typeform header, that appears when you have a Question group, or a long question that you need to scroll through to answer, like a Multiple Choice block. Boolean false

    #### Example:

    typeformEmbed.makePopup(
      'https://admin.typeform.com/to/PlBzgL',
      {
        mode: 'drawer_left',
        autoOpen: true,
        autoClose: 350,
        hideScrollbars: true
      }
    )

Troubleshooting

An element in my page is over the typeform

For the modal modes (popup, drawer and mobile), we use a z-index of 1000 by default. Take this into account when you want an element to be over or under the typeform modal.

When loading a typeform in mobile, a screen with the typeform name and a 'Start' button appears before the typeform

To get the best experience, on mobile all embedded typeforms are oppened in a fullscreen modal. The popup type behaves as expected, but a widget on mobile has an additional screen to launch the modal. This screen includes the typeform title and a button to lanch the typeform itself.

If you want to override this behaviour, the best option is to use the API with makePopup to open the typeform modal when you decide.

After opening a typeform in mobile, a <meta name="viewport" tag is added to the document

This tag is needed for the correct visualization of the typeform. This is only a problem if you don't have this tag in your site.

Transparency is not applied on mobile

We do not apply transparency on modals, and all embed types behave like a modal in mobile.

Typeform does not look good with a small embed

Although we have no hard limit, we recommend having a height of at least 350px.

Feedback

We are always open to your feedback.

Contribution

We'd love to have your helping hand on typeform's embed. See CONTRIBUTING.md for more information on what we're looking for and how to get started.

Device support

  • last 2 versions of major devices
  • internet explorer >= 9
  • safari >= 7

Browserlist support