@typeform/embed

What is @typeform/embed?

@typeform/embed is an npm package that allows you to easily embed Typeform forms into your web applications. It provides various methods to integrate Typeform forms, including pop-ups, sliders, and inline embeds, making it versatile for different use cases.

What are @typeform/embed's main functionalities?

Inline Embed

This feature allows you to embed a Typeform directly into a specified container on your webpage. You need to provide the Typeform ID and the container element where the form should be rendered.

const { createWidget } = require('@typeform/embed');

createWidget('YOUR_TYPEFORM_ID', {
  container: document.querySelector('#typeform-container')
});

Popup Embed

This feature allows you to create a Typeform that opens in a popup when triggered. You need to provide the Typeform ID and set up an event listener to open the popup.

const { createPopup } = require('@typeform/embed');

const openPopup = createPopup('YOUR_TYPEFORM_ID');

document.querySelector('#open-popup-button').addEventListener('click', () => openPopup());

Slider Embed

This feature allows you to create a Typeform that slides in from the side of the screen. You need to provide the Typeform ID and set up an event listener to open the slider.

const { createSlider } = require('@typeform/embed');

const openSlider = createSlider('YOUR_TYPEFORM_ID');

document.querySelector('#open-slider-button').addEventListener('click', () => openSlider());

Other packages similar to @typeform/embed

react-typeform-embed

react-typeform-embed is a React component library for embedding Typeform forms in React applications. It offers similar functionalities to @typeform/embed but is specifically designed for React, making it easier to integrate into React projects.

typeform

typeform is another npm package that provides a JavaScript API for interacting with Typeform forms. It offers more advanced functionalities like form creation and response retrieval, which are not available in @typeform/embed.

surveyjs

surveyjs is a library for creating surveys and forms, similar to Typeform. It offers a wide range of customization options and supports various frameworks like React, Angular, and Vue. While it is not specifically for Typeform, it provides similar functionalities for creating and embedding forms.

README

🛠 Typeform Vanilla Embed Library

Typeform/embed is the core embed library that lets you embed typeforms to your website using vanilla JavaScript.

Installation

As NPM package

Requirements:

• node >= 18
• yarn or npm

Install using your favourite package manager:

yarn add @typeform/embed

or

npm install --save @typeform/embed

Import the lib, CSS and create your embed:

import { createWidget } from '@typeform/embed'
import '@typeform/embed/build/css/widget.css'
createWidget('<form-id>', { container: document.querySelector('#form') })

From CDN

As HTML, the CSS is imported automatically. Place this code where you want to display your form.

<div data-tf-widget="<form-id>"></div>
<script src="//embed.typeform.com/next/embed.js"></script>

Via JavaScript for more control and specific integration.

<button id="button">open form</button>
<script src="//embed.typeform.com/next/embed.js"></script>
<link rel="stylesheet" href="//embed.typeform.com/next/css/popup.css" />
<script>
  const { open, close, toggle, refresh } = window.tf.createPopup('<form-id>')
  document.querySelector('#button').onclick = toggle
</script>

How to get form id of your form?

You can find <form-id> from the public URL of your form:

• https://form.typeform.com/to/<form-id>

Or from admin panel URL:

• https://admin.typeform.com/form/<form-id>/*

Limitations

For security purposes we prevent embedding typeorms in unsecure pages (via CSP headers). You can embed your typeform on pages served over HTTPS or via HTTP on localhost. You can also embed in wrapped progressive web apps.

Configuration

Embed types

Widget

<div id="form"></div>
<script>
  const { refresh, unmount } = createWidget('<form-id>', {
    container: document.querySelector('#form'),
    ...options,
  })
</script>

The createWidget method returns 2 functions:

• refresh - reloads the form
• unmount - unmounts the form (you should use this when you implement this lib in React manually)

Modal windows: popup, slider, sidetab, popover

• popup: createPopup('<form-id>', options)
• slider: createSlider('<form-id>', options)
• sidetab: createSidetab('<form-id>', options)
• popover: createPopover('<form-id>', options)

<button id="button">open form</button>
<script>
  const { open, close, toggle, refresh } = createPopup('<form-id>')
  document.querySelector('#button').onclick = toggle
</script>

Each of the create* methods for modal windows return 4 functions:

• open - open the modal window (popup, slider, sidetab or popover) and display the form
• close - close the modal window and hide the form
• toggle - open when closed, close when opened
• refresh - reloads the form
• unmount - unmounts the form (you should use this when you implement this lib in React manually)

Closing and opening a typeform in modal window will restart the progress from the beginning. However answers will be saved in browsers local storage.

Options

options is an object with optional properties:

name	type	description	default
container	HTMLElement	specify element to place the embed into, only for widget, required	current element when embedding as HTML, otherwise undefined
position	string	slider position: right or left	right
size	number	size of the popup in percentage (desktop only, opens in fullscreen on mobile devices)	100 (100% size, fullscreen popup)
width	number / string	width of the embed - number in pixels or string including units (for popup you can specify size instead)	undefined
height	number / string	height of the embed - number in pixels or string including units, supported by all embeds except slider (for popup you can specify size instead)	undefined
hidden	object	hidden fields to be passed to the form in URL hash	undefined
tracking	object	tracking parameters to be passed to the form in URL query string	undefined
source	string	domain name of the site using the SDK	domain name from window.location
medium	string	name of the plugin built on top of the SDK	"embed-sdk"
mediumVersion	string	version of the plugin built on top of the SDK	"next"
transitiveSearchParams	string[] / boolean	search parameters to be forwarded from host page to form, if true will forward all host page search parameters	undefined
hideFooter	boolean	hide form progress bar and navigation buttons	false
hideHeaders	boolean	hide header that appears when you have a question group, or a long question	false
domain	string	domain name of the environment the SDK should run against	"https://form.typeform.com"
opacity	number	form background opacity, number from 0 (fully transparent) 100 (fully opaque)	100
autoFocus	boolean	enable form auto focus when loaded	false
open	string	open embed based on user action (see below)	undefined
openValue	number	based on open (see below)	undefined
preventReopenOnClose	boolean	prevent automatically re-opening the typeform	false
enableSandbox	boolean	enable sandbox mode (disables submissions and tracking, the responseId in callbacks will have value of "__sandbox")	false
buttonText	string	customize the button text (sidetab only)	"Launch me"
buttonColor	string	customize the button background color (sidetab only)	#3a7685
buttonTextColor	string	customize the button text color (sidetab only)	white or black (based on background color)
buttonTextSize	integer / string	customize the button text size - number in pixels or string including units (sidetab only)	24px
buttonWidth	integer / string	customize the button width - number in pixels or string including units (sidetab only)	auto
buttonHeight	integer / string	customize the button height - number in pixels or string including units (sidetab only)	48px
buttonAlign	top / center / bottom	customize button position relative to form iframe (sidetab only)	center
top	integer / string	customize iframe position from top - number in pixels or string including units (sidetab only)	50%
bottom	integer / string	customize iframe position from bottom - number in pixels or string including units, can be used only when top is not set (sidetab only)	undefined
customIcon	string	customize the message icon (popover, sidetab) more info	undefined
tooltip	string	display tooltip text next to the button (popover only)	undefined
notificationDays	number	display red notification dot, hide for given number of days since popover is open (popover only)	undefined
autoClose	number / boolean	time (ms) until the embedded typeform will automatically close after a respondent clicks the Submit button. (all embeds except widget)	undefined
onReady	function	fires when the form is loaded	undefined
onStarted	function	fires on the "submission start" event, contains responseId in the payload	undefined
onSubmit	function	fires when user submits the form	undefined
onClose	function	fires when the form is closed (when opened in modal window)	undefined
onQuestionChanged	function	fires when user navigates between form questions	undefined
onHeightChanged	function	fires when form question height changes (eg. on navigation between questions or on error message)	undefined
onEndingButtonClick	function	fires when button on ending screen is clicked, disables button redirect functionality	undefined
onDuplicateDetected	function	fires when the respondent reaches the quota of responses defined in the duplicate prevention setting	undefined
autoResize	string / boolean	resize form to always fit the displayed question height, avoid scrollbars in the form (inline widget only), set min and max height separated by coma, eg. "200,600"	false
shareGaInstance	string / boolean	shares Google Analytics instance of the host page with embedded typeform, you can provide your Google Analytics ID to specify which instance to share (if you have more than one in your page)	false
inlineOnMobile	boolean	removes placeholder welcome screen in mobile and makes form show inline instead of fullscreen	false
iframeProps	object	HTML attributes to be passed directly to the iframe with typeform	undefined
buttonProps	object	HTML attributes to be passed directly to the button created by embed SDK (only for popover and sidetab)	undefined
lazy	boolean	enable lazy loading (for widget only), typeform starts loading when user scrolls to it, see demo	false
keepSession	boolean	preserve form state when modal window is closed (and re-opened)	false
redirectTarget	string	target for typeforms with redirect, valid values are _self, _top, _blank or _parent (see docs on anchor target)	_parent
disableScroll	boolean	disable navigation between questions via scrolling and swiping	false
hubspot	boolean	enable HubSpot source tracking - for details see article Set up source tracking for HubSpot	false
fullScreen	boolean	enable full screen view, set <body> size, resize on screen resize - also when browser navbars are displayed on mobile	false
preselect	object	preselect answer to the first question (more info in help center)	undefined
respectOpenModals	all / same	do not open if there already is a modal with typeform open (same - same form, all - any form)	undefined
noScrollbars	boolean	do not render scrollbars — useful when used along autoResize	undefined

Options in plain HTML embed

• to embed via HTML without writing JavaScript code, use data-tf-widget="<form-id>" for widget embed (see example above)
• define options as data attributes with data-tf- prefix and dashes in name (eg. autoFocus becomes data-tf-auto-focus)
• set a boolean property to true by omitting attribute value, (eg. <div ... data-tf-disable-footer></div>
• pass function name for callbacks, eg. data-tf-on-ready="myReadyFunction" if this function is available on global scope (eg. window)
• to pass string[] use comma-separated string, eg. transitiveSearchParams: ['foo', 'bar'] becomes data-tf-transitive-search-params="foo,bar"
• to pass object pass comma-separated key=value pairs, eg. hidden: { foo: "f", bar: "b" } becomes data-tf-hidden="foo=f,bar=b"
  • Note: since commas , are used as delimiter for each value you will need to escape them with backward slash, eg. data-tf-hidden="foo=foo\,bar". In JavaScript you don't need to escape it.

Custom Launch Options

Properties open and openValue apply only to embed types that are opened by user action (all except widget). They define when to automatically open the typeform.

• on page load
  • open: 'load'
  • openValue leave undefined (not used)
• when user tries to leave the page
  • open: 'exit'
  • openValue specify the sensitivity threshold
  • To detect user is trying to exit the page we detect upwards mouse movement in top part of the website. The threshold defines height of this area. Useful when you have navigation in top part of your website and mouse movement in that area does not necessarily indicate exit intent.
• when a user scrolls the page
  • open: 'scroll'
  • openValue percentage of page scrolled (0 - 100) to open the form
• after time elapsed
  • open: 'time'
  • openValue number of milliseconds to wait before opening the form

For details see behavioral demo.

Share Google Analytics Instance

You can use shareGaInstance: true (or data-tf-share-ga-instance) attribute if both your page and your typeform are using Google Analytics. This will make sure the session is shared and Google Analytics will track only 1 user when they visit you page with an embedded typeform.

If you have more than 1 Google Analytics tracking codes in your website you can provide an ID to specify which tracker to use, eg:

<div data-tf-widget="<form-id>" data-tf-share-ga-instance="UA-XXXXXX-XX"></div>

or

createPopup('<form-id>', { container, shareGaInstance: 'UA-XXXXXX-XX' })

Callbacks

You can listen to form events by providing callback methods:

<button id="btn">click</button>
<script src="//embed.typeform.com/next/embed.js"></script>
<link rel="stylesheet" href="//embed.typeform.com/next/css/widget.css" />
<script>
  const { open } = window.tf.createPopup('<form-id>', {
    onReady: ({ formId }) => {
      console.log(`Form ${formId} is ready`)
    },
    onStarted: ({ formId, responseId }) => {
      console.log(`Form ${formId} started with response ID ${responseId}`)
    },
    onQuestionChanged: ({ formId, ref }) => {
      console.log(`Question in form ${formId} changed to ${ref}`)
    },
    onHeightChanged: ({ formId, ref, height }) => {
      console.log(`Question ${ref} in form ${formId} has height ${height}px now`)
    },
    onSubmit: ({ formId, responseId }) => {
      console.log(`Form ${formId} submitted, response id: ${responseId}`)
      // to retrieve the response use `responseId` (you have to do it server-side)
      // more details: https://developer.typeform.com/responses/
    },
    onClose: ({ formId }) => {
      console.log(`Modal window with form ${formId} was closed`)
    }
    onEndingButtonClick: ({ formId, ref }) => {
      console.log(`Ending button clicked in form ${formId}`)

      // for plans with "Redirect from ending screen" feature you also receive `ref`:
      console.log(`Ending button clicked in end screen ${ref}`)
    },
    onDuplicateDetected: ({ formId }) => {
      console.log(`User reached the quote of responses for form ${formId}`)
    }
  })
  document.querySelector('#btn').click = () => {
    open()
  }
</script>

Callback method receive payload object from the form. Each payload contains form ID to identify which form sent the event (see chaining typeforms below):

• onReady
  • formId (string)
• onStarted
  • formId (string)
  • responseId (string)
• onQuestionChanged
  • formId (string)
  • ref (string) identifies currently displayed question
• onHeightChanged
  • formId (string)
  • ref (string) identifies currently displayed question
  • height (number) current height of currently displayed question
• onSubmit
  • formId (string)
  • responseId (string) identifies the response, can be retrieved via Responses API
• onClose
  • no payload
• onEndingButtonClick
  • formId (string)
  • ref (string) identifies the end screen (Note: this is available for plans with "Redirect from ending screen" feature only.)
• onDuplicateDetected
  • formId (string)

See callbacks example in demo package.

Custom icon

Custom icon provided string supports:

• URL (used as an img src)
• Text and Emojis
• HTML Markup

Redirect Target

You can supply a target for typeform redirect (on submit or via ending). It works the same as target for anchor HTML element:

• _parent (default), opens in parent page
• _self opens in the same embedded iframe as your typeform
• _top opens in current browser tab (same as _parent unless there are multiple nested iframes)
• _blank opens in new tab, however it might be blocked by popup blockers.

⚠️ Warning: Target _blank is not working in Safari (both desktop and mobile) and triggers a popup warning in Chrome on Android. It works in Chrome and Firefox on desktop.

If you set target to _self and also enable autoClose option the iframe with your redirect will be closed before users are able to interact with it.

Positioning and overlapping

All embeds that are intended to be displayed over existing content in the website have z-index set to 10001. If you want to display content over your typeform you need to make sure it has higher z-index. However if you want your typeform to display over other content in your website you need to set its z-index to a value of 10000 or lower.

This is related to all embeds:

• popup
• slider
• sidetab
• popover
• widget - on mobile devices widget opens in fullscreen modal window (unless inlineOnMobile is set)

Chaining typeforms

You can chain multiple typeforms inside an embed. You need to setup a redirect to another typeform:

• make sure to use URL with typeform.com domain in case you have a custom domain set up
• set redirectTarget / data-tf-redirect-target to _self to make the redirect inside the embed iframe

When you chain multiple typeforms they will be all displayed inside the embed and all embed options and callbacks will be preserved. You can use formId in the callback payload to identify which form is currently displayed.

Loading and reloading embedded forms

When the library loads it will initialize all HTML embed codes already present in the page. However sometimes you might want to add HTML snippet to your page later and initialize it after it was added.

To load new snippets use:

window.tf.load()

If you need to reload all snippets in the page:

window.tf.reload()

You can see an example of this in reload-event.html.

Examples

You can find examples for specific use-cases in our demos:

• HTML demo
• Webpack demo
• React demo
• Next.js demo
• Codesandbox demo

Local setup and development

Fork and clone this Github repo: https://github.com/Typeform/embed

Requirements:

• node >= 18
• yarn

Install dependencies:

yarn

We recommend you work in a branch:

git checkout -b cool-new-feature

Build, watch for changes and start a demo server too (using demo-nextjs)

yarn demo

Build and watch for changes:

yarn dev

Run unit tests:

yarn test

Run functional tests via Cypress:

yarn cy:run   # run in background (headless)
yarn cy:open  # open cypress UI

Run visual tests via Cypress and VRT:

yarn cy:visual    # run in background (headless)
yarn cy:open:vrt  # open cypress UI (with support for VRT)

Note: You need access to our self-hosted Visual Regression Tracker (aka VRT). Copy vrt.example.json to vrt.json and provide apiKey to run visual tests locally.

See details on contributing to this repo.