Logic Jumps | Typeform

This walkthrough will help you use Logic Jumps when you’re creating or updating a form with the Create API.

If you’re not familiar with Typeform’s Logic Jump concept, this Help Center article is a great introduction to the basics. Some Logic Jump capabilities rely on Hidden Fields, so it’s a good idea to get to know Hidden Fields too.

Here’s an example Logic Jump:

{
  "logic": [
    {
      "type": "field",
      "ref": "ref_trigger_field",
      "actions": [
        {
          "action": "jump",
          "details": {
            "to": {
              "type": "field",
              "value": "ref_field_leads_to"
            }
          },
          "condition": {
            "op": "equal",
            "vars": [
              {
                "type": "field",
                "value": "ref_another_field"
              },
              {
                "type": "constant",
                "value": 10
              }
            ]
          }
        }
      ]
    }
  ]
}

The three main parts of this Logic Jump are the type and ref definitions, the to object, and the condition object. Here’s how they work together in a Logic Jump:

The type and ref definitions identify which field triggers the Logic Jump.
The to object identifies which field or screen the Logic Jump leads to.
The condition object sets the conditions for executing the Logic Jump.

Let’s look at each of the three parts in detail.

Part 1: `type` and `ref` definitions

The type and ref definitions identify the field that triggers the Logic Jump. This part answers the question, “Where from?”

Logic Jumps can be triggered by the answer to a question or by a hidden field value. You can jump from a field based on an answer or jump to a field or skip fields based on a Hidden Field value. Both types of Logic Jumps must include the actions array, which will contain the other two parts of the Logic Jump (the to and condition objects).

A Logic Jump triggered by the answer to a question includes type and ref definitions, in addition to the actions array:

{
  "type": "field",
  "ref": "ref_trigger_field",
  "actions": [...]
}

A Logic Jump triggered by a Hidden Field value only includes a type definition and the actions array:

{
  "type": "hidden",
  "actions": [...]
}

Here’s a description of each element in the type and ref definitions:

Element	Type	Description	Required?
`type`	string	Identifies which Logic Jump “from” option you are using. Valid values are `field` and `hidden`.	Required
`ref`	string	Unique ID you will use to refer to this Logic Jump. Must be less than 255 characters and in valid regular expression format `^[a-zA-Z0-9_-]+$`.	Required for field Logic Jumps. Not used for hidden Logic Jumps.
`actions`	array of objects	Array of objects that define the Logic Jump’s behavior.	Required

Logic Jump definitions are unique per triggering field. Per form, there should be at most one Logic Jump definition with "type": "hidden" and at most one Logic Jump definition for each field ("type": "field"). Multiple jump conditions can be defined inside the actions array.

For example, this is not valid, because it has two Logic Jump definitions for the field ref_trigger_field:

{
  "logic": [
    {
      "type": "field",
      "ref": "ref_trigger_field",
      "actions": [{...}]
    },
    {
      "type": "field",
      "ref": "ref_trigger_field",
      "actions": [{...}]
    },
    {
      "type": "field",
      "ref": "ref_another_trigger_field",
      "actions": [{...}]
    }
  ]
}

In this case, the correct format should be to merge actions from the two definitions of field ref_trigger_field into a single one:

{
  "logic": [
    {
      "type": "field",
      "ref": "ref_trigger_field",
      "actions": [{...}, {...}]
    },
    {
      "type": "field",
      "ref": "ref_another_trigger_field",
      "actions": [{...}]
    }
  ]
}

Part 2: The `to` object

The to object defines where the Logic Jump leads to — it answers the question, “Where to?” You have three options: a field in the form, the default thank-you screen, or a custom thank-you screen.

Here’s an example object for a Logic Jump to a field in the form:

{
  "action": "jump",
  "details": {
    "to": {
      "type": "field",
      "value": "ref_field_leads_to"
    }
  }
}

And for a jump to the default thank-you screen:

{
  "action": "jump",
  "details": {
    "to": {
      "type": "thankyou",
      "value": "default"
    }
  }
}

And for a jump to a custom thank-you screen:

{
  "action": "jump",
  "details": {
    "to": {
      "type": "thankyou",
      "value": "thankyou_screen_reference"
    }
  }
}

Here’s a description of each element in this to object:

Element	Type	Description	Required?
`action`	string	Behavior the Logic Jump will take. Valid values include `jump`, `add`, `subtract`, `multiply`, and `divide`.	Required
`details`	object	Properties that specify how the Logic Jump will behave.	Required
`to`	object	Elements that define where the Logic Jump leads to.	Required
`type`	string	Identifies which Logic Jump “to” option you are using. Valid values are `field` and `thankyou`.	Required
`value`	string	ref value for the field or thank-you screen where the Logic Jump leads to. Valid values include the ref for any field in the form, the ref for any custom thank-you screen, and `default` for the default thank-you screen.	Required

Note

You can use Logic Jumps for more than jumping to a question! If your form adds up the prices of different items or keeps a score and provides a total at the end, use target and value instead of to.

The POST https://api.typeform.com/forms endpoint includes a schema explanation.

Part 3: The `condition` object

In the condition object, you specify the conditions for executing your Logic Jump. The conditions answer the question, “Under what circumstances?” The condition object is the IF statement in your Logic Jump.

In plain language, a condition would be something like “Execute the jump if the numeric answer for Question X is less than 5” or “Execute the jump if the person answers “No” to the legal agreement.” In code, it looks quite different!

In our example, the Logic Jump should execute when a respondent answers “10” in the field with the ref “readable field reference”.

{
  "condition": {
    "op": "equal",
    "vars": [
      {
        "type": "field",
        "value": "ref_another_field"
      },
      {
        "type": "constant",
        "value": 10
      }
    ]
  }
}

Here’s a description of each element in the condition object:

Element	Type	Description	Required?
`condition`	object	Conditions for executing the Logic Jump.	Required
`op`	string	Operator for the condition. Valid values depend on the field type: text, numeric, choice, date, file upload, or hidden — see subsections below for details.	Required
`vars`	array of objects	Elements that define the field type and value to evaluate with the operator.	Required
`type`	string	Type of value the condition object refers to. Valid values are `field`, `hidden`, `variable`, `constant`, and `end`.	Required
`value`	string	Value to check for in the type field to evaluate with the operator.	Required

Read on for details about the operators (op) you can use for each field type.

All fields

Operator	Meaning
`always`	Always execute the jump

Example:

{
  "op": "always",
  "vars": []
}

For the always operator, you don’t need to specify any vars. Your typeform will always execute this Logic Jump.

Operator	Meaning
`equal`	Execute jump if field answer equals specified value
`not_equal`	Execute jump if field answer does not equal specified value
`begins_with`	Execute jump if field answer starts with specified value
`ends_with`	Execute jump if field answer ends with specified value
`contains`	Execute jump if field answer contains specified value
`not_contains`	Execute jump if field answer does not contain specified value

Example: Execute jump if text field answer matches specified value

{
  "op": "equal",
  "vars": [
    {
      "type": "field",
      "value": "text_field_ref"
    },
    {
      "type": "constant",
      "value": "Mamon"
    }
  ]
}

Numeric fields (rating, opinion scale, number)

For conditions based on numeric fields, the specified value must be an integer.

Operator	Meaning
`equal`	Execute jump if field answer equals specified value
`not_equal`	Execute jump if field answer does not equal specified value
`lower_than`	Execute jump if field answer is less than specified value
`lower_equal_than`	Execute jump if field answer is less than or equal to specified value
`greater_than`	Execute jump if field answer is greater than specified value
`greater_equal_than`	Execute jump if field answer is greater than or equal to specified value

Example: Execute jump if numeric answer is less than the specified value

{
  "op": "lower_than",
  "vars": [
    {
      "type": "field",
      "value": "numeric_field_ref"
    },
    {
      "type": "constant",
      "value": "3"
    }
  ]
}

Choice fields (text choice, picture choice, yes/no, legal)

Operator	Meaning
`is`	Execute jump if field answer matches the ref of the choice (for text choice and picture choice fields) or specified Boolean value (for yes/no and legal fields).
`is_not`	Execute jump if field answer does not match the ref of the choice (for text choice and picture choice fields) or specified Boolean value (for yes/no and legal fields).

Example: Execute jump if picture choice or text choice answer matches the ref of the choice

{
  "op": "is",
  "vars": [
    {
      "type": "field",
      "value": "picture_or_text_choice_field_ref"
    },
    {
      "type": "choice",
      "value": "multiple_choice_ref"
    }
  ]
}

Example: Execute jump if yes/no or legal answer matches specified Boolean value

{
  "op": "is",
  "vars": [
    {
      "type": "field",
      "value": "yes_no_or_legal_field_ref"
    },
    {
      "type": "constant",
      "value": true
    }
  ]
}

Date field

Operator	Meaning
`on`	Execute jump if field answer matches specified date
`not_on`	Execute jump if field answer is not on specified date
`earlier_than`	Execute jump if field answer is earlier than specified date
`earlier_than_or_on`	Execute jump if field answer is earlier than or on specified date
`later_than`	Execute jump if field answer is later than specified date
`later_than_or_on`	Execute jump if field answer is later than or on specified date

Example: Execute jump if date field matches specified value

{
  "op": "on",
  "vars": [
    {
      "type": "field",
      "value": "date_field_ref"
    },
    {
      "type": "constant",
      "value": "2016-09-30"
    }
  ]
}

The date format is YYYY-MM-DD.

File upload field

Operator	Meaning
`answered`	Execute jump if respondent uploaded a file

Example:

{
  "op": "answered",
  "vars": [
    {
      "type": "field",
      "value": "file_upload_field_ref"
    },
    {
      "type": "constant",
      "value": true
    }
  ]
}

Hidden Field

Operator	Meaning
`equal`	Execute jump if Hidden Field equals specified value
`not_equal`	Execute jump if Hidden Field does not equal specified value
`begins_with`	Execute jump if Hidden Field starts with specified value
`ends_with`	Execute jump if Hidden Field ends with specified value
`contains`	Execute jump if Hidden Field contains specified value
`not_contains`	Execute jump if Hidden Field does not contain specified value

Example: Execute jump if referrer is “facebook”

{
  "op": "equal",
  "vars": [
    {
      "type": "hidden",
      "value": "referrer"
    },
    {
      "type": "constant",
      "value": "facebook"
    }
  ]
}

Best Practices for Logic Jumps

Follow these best practices to create Logic Jumps that work beautifully.

Use `ref` values that actually exist

This is the most important part of ensuring that your Logic Jumps work properly. Make sure that you don’t include a ref to a field that doesn’t exist in the typeform. And as always, watch for typos!

Place conditions in the correct order

If you include more than one condition in a Logic Jump, it’s important to put the conditions in the correct order so that the Logic Jump executes the way you want. The first condition that’s met will trigger the Logic Jump, and any subsequent conditions will be ignored.

For example, suppose you have multiple choice question, and respondents can pick more than one answer. If the answer is Mango, the form should skip to Question 3. If the answer is Mango and Apple, the form should skip to question 4.

For this Logic Jump to work properly, put the condition “If [Mango AND Apple], jump to Question 4” first—before the condition “If [Mango], jump to Question 3.”

Here’s what this looks like in code:

{
  "logic": [
    {
      "type": "field",
      "ref": "ref_text_choice_field",
      "actions": [
        {
          "type": "jump",
          "jump": {
            "to": {
              "type": "field",
              "value": "ref_question4"
            }
          },
          "condition": {
            "op": "and",
            "vars": [
              {
                "op": "is",
                "vars": [
                  {
                    "type": "field",
                    "value": "ref_text_choice_field"
                  },
                  {
                    "type": "constant",
                    "value": "ref_for_mango"
                  }
                ]
              },
              {
                "op": "is",
                "vars": [
                  {
                    "type": "field",
                    "value": "ref_other_text_choice_field"
                  },
                  {
                    "type": "constant",
                    "value": "ref_for_apple"
                  }
                ]
              }
            ]
          }
        },
        {
          "type": "jump",
          "jump": {
            "to": {
              "type": "field",
              "value": "ref_question3"
            }
          },
          "condition": {
            "op": "is",
            "vars": [
              {
                "type": "field",
                "value": "ref_text_choice_field"
              },
              {
                "type": "constant",
                "value": "ref_for_mango"
              }
            ]
          }
        }
      ]
    }
  ]
}

If you put “If [Mango], skip to Question 3” first, and a respondent answered [Mango AND Apple], the Logic Jump to Question 3 would execute because the answer contains “Mango.”

Place your most restrictive conditions first

When you’re organizing the order of your Logic Jumps, place your most restrictive conditions first, followed by your more general conditions.

For example, if you have the conditions “answer begins with b” and “answer is boat”, place the condition “answer is boat” first because it’s more restrictive.

Use `AND` and `OR` operators correctly

You can use AND and OR operators to add several conditions to a single Logic Jump, but it’s important to use the correct operators in the correct order to achieve the result you want.

Imagine that this is Question 1: “Select your favorite fruits.” The answer choices are Apple, Orange, and Mango. Respondents can select one, two, or all three choices.

Here’s what the Logic Jump code should look like for the scenario IF answer is [Apple AND Orange] OR [Mango], jump to Question 3:

{
  "logic": [
    {
      "type": "field",
      "ref": "ref_text_choice_field",
      "actions": [
        {
          "type": "jump",
          "jump": {
            "to": {
              "type": "field",
              "value": "ref_question3"
            }
          },
          "condition": {
            "op": "or",
            "vars": [
              {
                "op": "and",
                "vars": [
                  {
                    "op": "is",
                    "vars": [
                      {
                        "type": "field",
                        "value": "ref_text_choice_field"
                      },
                      {
                        "type": "constant",
                        "value": "apple"
                      }
                    ]
                  },
                  {
                    "op": "is",
                    "vars": [
                      {
                        "type": "field",
                        "value": "ref_text_choice_field"
                      },
                      {
                        "type": "constant",
                        "value": "orange"
                      }
                    ]
                  }
                ]
              },
              {
                "op": "is",
                "vars": [
                  {
                    "type": "field",
                    "value": "ref_text_choice_field"
                  },
                  {
                    "type": "constant",
                    "value": "ref_for_mango"
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

And here’s what the Logic Jump code should look like for the scenario IF answer is [Apple AND Orange] OR [Apple AND Mango], jump to Question 3:

{
  "logic": [
    {
      "type": "field",
      "ref": "ref_text_choice_field",
      "actions": [
        {
          "type": "jump",
          "jump": {
            "to": {
              "type": "field",
              "value": "ref_question3"
            }
          },
          "condition": {
            "op": "or",
            "vars": [
              {
                "op": "and",
                "vars": [
                  {
                    "op": "is",
                    "vars": [
                      {
                        "type": "field",
                        "value": "ref_text_choice_field"
                      },
                      {
                        "type": "constant",
                        "value": "apple"
                      }
                    ]
                  },
                  {
                    "op": "is",
                    "vars": [
                      {
                        "type": "field",
                        "value": "ref_text_choice_field"
                      },
                      {
                        "type": "constant",
                        "value": "orange"
                      }
                    ]
                  }
                ]
              },
              {
                "op": "and",
                "vars": [
                  {
                    "op": "is",
                    "vars": [
                      {
                        "type": "field",
                        "value": "ref_text_choice_field"
                      },
                      {
                        "type": "constant",
                        "value": "apple"
                      }
                    ]
                  },
                  {
                    "op": "is",
                    "vars": [
                      {
                        "type": "field",
                        "value": "ref_text_choice_field"
                      },
                      {
                        "type": "constant",
                        "value": "mango"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

Avoid sending respondents back to a question that they haven’t visited

Logic Jumps can only jump to a previous question if the respondent has already visited that question. So for example, if a respondent bypassed Question A in Logic Jump X, you can’t send the respondent back to Question A in Logic Jump Y. Place the question or statement that a Logic Jump leads to after the question that triggers the Logic Jump.

Multi-branching

Multi-branching allows you to ask follow-up questions based on answers to a previous question. For example, if a respondent answers the multiple-choice question, “Which book do you prefer? A. Charlotte’s Web B. James and the Giant Peach” by selecting Charlotte’s Web, you can create multi-branch Logic Jumps to ask follow-up questions specific to Charlotte’s Web and skip questions related to James and the Giant Peach. Here are some best practices for multi-branching.

Define a Logic Jump at the beginning of each branch

The question that comes before a branch must be a Logic Jump. If you forget to include a Logic Jump before a branch, respondents could end up in a branch of questions that don’t make sense based on their previous answers.

For example, if you forget to include a Logic Jump on the multiple-choice question, “Which book do you prefer? A. Charlotte’s Web B. James and the Giant Peach”, respondents who answer “A. Charlotte’s Web” will still see questions about James and the Giant Peach.

Include follow-up questions for all possible answers to the “trigger” question

Make sure that your Logic Jumps include follow-up questions for all the possible answers (or combinations of answers). To continue our “Which book do you prefer?” example, you’d need two branches: one for the answer A. Charlotte’s Web and one for the answer B. James and the Giant Peach. If you offer a third answer choice, C. Watership Down, you’d need a third branch in case respondents choose answer C.

Now, consider how many branches you’d need for the question, “Which of these books do you enjoy? A. Charlotte’s Web B. James and the Giant Peach”. For this question, respondents could choose only A., only B., both A. and B., or neither A. or B. So you’d need four branches.

Include as many Logic Jumps as you need

There’s no limit to the number of Logic Jumps you can include — here’s an example typeform that uses more than 100! As long as your Logic Jumps are set up properly, you can use as many as you need to give your respondents a great experience.

What’s next?

Learn more about how Hidden Fields work in the Create API. Or, check out the Create reference for endpoints.

Part 1: type and ref definitions

Part 2: The to object

Part 3: The condition object

All fields

Example:

Text fields (short text, long text, dropdown, email, website)

Numeric fields (rating, opinion scale, number)

Example: Execute jump if numeric answer is less than the specified value

Choice fields (text choice, picture choice, yes/no, legal)

Example: Execute jump if picture choice or text choice answer matches the ref of the choice

Example: Execute jump if yes/no or legal answer matches specified Boolean value

Date field

Example: Execute jump if date field matches specified value

File upload field

Example:

Hidden Field

Example: Execute jump if referrer is “facebook”

Best Practices for Logic Jumps

Use ref values that actually exist

Place conditions in the correct order

Place your most restrictive conditions first

Use AND and OR operators correctly

Avoid sending respondents back to a question that they haven’t visited

Multi-branching

Define a Logic Jump at the beginning of each branch

Include follow-up questions for all possible answers to the “trigger” question

Include as many Logic Jumps as you need

What’s next?

Part 1: `type` and `ref` definitions

Part 2: The `to` object

Part 3: The `condition` object

Use `ref` values that actually exist

Use `AND` and `OR` operators correctly