Typeform JavaScript SDK

JS Client wrapper for Typeform API

Table of contents

• Installation
• Usage
  • Initialise
• Reference
  • Create Client
  • Forms
  • Images
  • Teams
  • Themes
  • Workspaces
• Examples
• Testing
• Suggestions

Installation

# install with yarn
yarn add @typeform/js

# install with npm
npm install @typeform/js --save

Usage

Intialise

1. Import client library

  import {createClient} from '@typeform/js'

2. Create a instance with your personal token

  const typeformAPI = createClient({
    token: '<your token>'
  })

3. Use any of the methods available in the reference

  // will retrieve all forms
  typeformAPI
    .forms
    .list()
    .then(response => {
      // do what do you want with your typeforms
    })

Reference

createClient({token})

• Creates a new instance of Typeform's JS client
• Returns an instance with the methods described below

  const typeformClient = createClient({
    token: '<your token>'
  })

Client returns the following properties:

• forms
• images
• teams
• workspaces
• themes

Each one of them encapsulates the operations related to it (like listing, updating, deleting the resource).

Forms

forms.list({ page: 1, page_size: 10, search: '' })

• Get a list of your typeforms
• Returns a list of typeform with the payload refenced here.

forms.get({ uid })

• Get a typeform by UID
• Returns a typeform with the payload refenced here.

forms.update({ uid, data = {}, override: false })

• Get a typeform by UID
• Returns a typeform with the payload refenced here.

forms.delete({ uid })

forms.messages.get({ uid })

• Get custom messages typeform of a given UID

forms.messages.update({ uid })

• Updates custom messages typeform of a given UID

Images

images.list()

• Get your images collection

images.get({ id, returns, size, backgroundSize, choiceSize })

• Get custom image by ID
• returns: json, binary (default)
• size: default, thumbnail, mobile,
• backgroundSize: default, thumbnail, mobile, tablet
• choiceSize: default, thumbnail, supersize, supermobile, supersizefit, supermobilefit

images.add({ image, media_type, file_name })

• Update an image to Typeform

images.delete({ id })

• Deletes an image with the given ID

Teams

teams.get({ id })

• Gets team information for the given ID

teams.addMembers({ id, members })

• Add members to a team for the given ID
• members: string or an array and should be the email fo the user
• Adding multiple members at once is possible using an array of emails

teams.removeMembers({ id, members })

• Remove members to a team for the given ID
• members: string or an array and should be the email fo the user
• Deleting multiple members at once is possible using an array of emails

Themes

themes.list({ page, page_size })

• Gets your themes collection
• page: default 1
• page_size: default 10`

themes.get({ id })

• Gets a theme for the given ID

themes.create({ background, colors, font, has_transparent_button, name })

• Creates a theme with the given configuration
• See more details of the payload in the documentation

themes.update({ background, colors, font, has_transparent_button, name })

• Creates a theme with the given configuration
• See more details of the payload in the documentation

themes.delete({ id })

• Deletes the theme with the given ID

Workspaces

workspaces.list({ page, page_size, search })

• Gets your workspaces
• page: default 1
• page_size: default 10`
• search: search a workspace that partially matches the search string

workspaces.get({ id })

• Gets the workspace information for the given ID

workspaces.update({ id, data })

• Gets the workspace information for the given ID
• data: operation that is wanted to perform, see more details in the documentation

workspaces.delete({ id })

• Deletes the workspace for the given ID

workspaces.get({ id })

• Gets the workspace information for the given ID

workspaces.addMembers({ id, members })

• Add members to a workspace for the given ID
• members: string or an array and should be the email fo the user
• Adding multiple members at once is possible using an array of emails

workspaces.removeMembers({ id, members })

• Remove members to a workspace for the given ID
• members: string or an array and should be the email fo the user
• Removing multiple members at once is possible using an array of emails

Examples

Update specific typeform property, as referenced here

  typeformClient
    .forms
    .update({
      uid: 'asdf',
      data: [
        {
          "op": "replace",
          "path": "/title",
          "value": 'new title'
        }
      ]
    })
    .then(response => {
      //... 
    })

Update the whole typeform

  typeformClient
    .forms
    .update({
      uid: 'asdf',
      override: true,
      data: {
        "title": newTitle,
        "theme": {
          "href": "https://api.typeform.com/themes/6lPNE6"
        }
      }
    })
    .then(response => {
      //... 
    })

Note: The theme property applies a theme to the form. If you don't specify a value for the 'theme' property, Typeform applies a new copy of the default theme to the form, even if you already have a copy of the default theme applied to this form.

Uploading an image

  typeformClient
    .images
    .add({
      "image": "bGRqZmxzZGpmbHNoZmtoc2RrZmpoc2tqZA==",
      "media_type": "image/gif",
      "file_name": "newimage.gif"
    })
    .then(response => {
      //...
    })

Getting the thumbnail of an image

  typeformClient
    .images
    .get({ id: 'asdf', size: 'thumbnail' })
    .then(response => {
      //...
    })

Testing

The project has implemeted unit and integration tests.

yarn install

# Runs unit tests
yarn test:unit

# Runs integration tests 
TYPEFORM_TOKEN='<your personal token>' yarn test:integration

Suggestions

Fill out this typeform 🙂