Embed
Typeform/embed is the client-side script and a CommonJS module that allows you to integrate a typeform into your website easily.
This README file contains instructions to embed typeform into your website. If you are looking to set up the project locally for development and contribution, see CONTRIBUTING.md.
If you are not comfortable with frontend development you can embed typeform via code snippets
Getting Started
Requirements:
node
>= 12yarn
(ornpm
)
Installation
NPM package
We recommend to use yarn
as your package manager, and also a build tool like webpack or browserify in order to use it.
yarn add @typeform/embed
The NPM version doesn't include neither React, ReacDOM nor polyfills. It's a responsibility of the application to provide those deps as peer dependencies and control the environment polyfilling process.
CDN script
You can also consume the library from our CDN:
<script src="https://embed.typeform.com/embed.js"></script>
<!-- this script exposes the API to `window.typeformEmbed` -->
The CDN version has everything bundled, so the script is ready to use out-of the box. It contains react, react-dom, and polyfills. If you believe everything is already injected in your environment globals you can use a more lightweight version, although it's not recommended:
<script src="https://embed.typeform.com/embed.pure.js"></script>
<!-- this script exposes the API to `window.typeformEmbed` -->
Usage
// Using ES6 imports
import * as typeformEmbed from '@typeform/embed'
// or require
const typeformEmbed = require('@typeform/embed')
With React Hooks
import React, { useRef, useEffect } from 'react';
import * as typeformEmbed from "@typeform/embed";
const MyTypeform = () => {
const typeformRef = useRef(null);
useEffect(() => {
typeformEmbed.makeWidget(typeformRef.current, 'https://form.typeform.com/to/MY_TYPEFORM_ID', {
hideFooter: true,
hideHeaders: true,
opacity: 0,
});
}, [typeformRef]);
return (
<div ref={typeformRef} style={{ height: '100vh', width: '100%'}}></div>
);
}
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 appears 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 onSubmit Callback function that will be executed right after the typeform is successfully submitted. Function
- onReady Callback function that will be executed once the typeform is ready. Function
- onScreenChanged Callback function that will be executed once the typeform's active screen changes. Function
- transferableUrlParameters Parameters that we want to transfert from the URL to the Typeform as hidden fields Array
[] source Domain name of the site using the SDK String
null medium Name of the plugin built on top of the SDK String
null mediumVersion Version of the plugin built on top of the SDK String
null 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, onSubmit: function () { console.log('Typeform successfully submitted') }, onReady: function () { console.log('Typeform is ready') } } )
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 The way of showing the popup String
any of:
"popup"
"drawer_left"
"drawer_right"
"popover"
"side_panel"
"popup" ❌ autoOpen Your typeform will launch as soon as your web page is opened Deprecated: Use open: "load"
insteadBoolean
false 💡 open Your typeform will launch based on behavioral triggers String
any of:
"exit"
"load"
"scroll"
"time"
null 💡 openValue Configuration for behavioral triggers. Based on open
:
-"exit"
: exit threshold in pixels
-"scroll"
: % of page scrolled
*"time"
: time in millisecondsNumber
null autoClose Time until the embedded typeform will automatically close after a respondent clicks the Submit button. The default time is 5 seconds. PRO+ users can change the autoClose
time.Number
(seconds)- 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 ❌ drawerWidth Specify the width of the drawer (only applies if using mode
"drawer_left"
or"drawer_right"
).Number
(pixels)width Specify the width of the drawer or popup (only applies if using mode
"drawer_left"
or"drawer_right"
or"popover"
or"side_panel"
).Number
(pixels)800 for "drawer_left"
and"drawer_right"
320 for"popover"
height Specify the height of the popup (only applies if using mode
"popover"
or"side_panel"
).Number
(pixels)500 size Specify the size of the popup (only applies if using mode
"popup"
).Number
(percent)100 onSubmit Callback function that will be executed right after the typeform is successfully submitted. Function
- onReady Callback function that will be executed once the typeform is ready. Function
- onScreenChanged Callback function that will be executed once the typeform's active screen changes. Function
- onClose Callback function that will be executed once the typeform is closed. Function
- container Element to place the popup into. Optional. Required only for "side_panel"
mode.DOM element
- transferableUrlParameters Parameters that we want to transfert from the URL to the Typeform as hidden fields Array
[] source Domain name of the site using the SDK String
null medium Name of the plugin built on top of the SDK String
null mediumVersion Version of the plugin built on top of the SDK String
null
Types:
- ❌ Deprecated option. Will be removed in future.
- 💡 Experimental option. Implementation might change in future without prior notice. Use at your own risk.
Example:
typeformEmbed.makePopup(
'https://admin.typeform.com/to/PlBzgL',
{
mode: 'drawer_left',
open: 'scroll',
openValue: 30,
autoClose: 3,
hideScrollbars: true,
onSubmit: function () {
console.log('Typeform successfully submitted')
},
onReady: function () {
console.log('Typeform is ready')
},
onClose: function () {
console.log('Typeform is closed')
}
}
)
More examples:
onSubmit
event
Callback function onSubmit
receives event
object with next properties:
Parameter | Type | Description |
---|---|---|
response_id |
string | ID of the response |
Example:
const reference = typeformEmbed.makePopup(
'https://admin.typeform.com/to/PlBzgL',
{
onSubmit: function (event) {
console.log(event.response_id)
}
}
)
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.
<meta name="viewport">
tag is added to the document
After opening a typeform in mobile, a 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.
Typeform does not look good with a small embed
Although we have no hard limit, we recommend having a height of at least 350px.
Typeform not visible after pressing 'Start' in mobile
We use position: fixed
to position our modal relative to its containing block established by the viewport. If one of the modal ancestors has a transform
, perspective
, or filter
css property set to something other than none
the positioning will be relative to it and probably not visible by the user.
Tests
In order to run visual tests, you need an applitools key.
- Add a
.env
file in your root, you can look at the.env.example
- Add your api key
EYES_API_KEY=HERE_GOES_YOUR_KEY
- (Optional) You can add the url, by default the url is
http://localhost:8080
- Start the server
yarn start
- Run the tests with
yarn test
-
- This command will run all the tests. That means unit tests, integration tests and visual tests
This is the list of all the test commands, if you want to run them one by one:
yarn test:unit
--> Runs unit testsyarn test:functional
--> Runs functional tests with Cypressyarn test:visual
--> Runs visual tests with Cypress and Applitools
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