End-User Guide - SurveyJS Creator
This page has been prepared as a starting point for documentation aimed at end-users of SurveyJS.
Basic Overview/Quick Start Guide
The SurveyJS Survey Creator page contains the survey design area with the Toolbox to the left and the Properties window to the right.
Survey elements (such as questions or panels) can be dragged from the toolbox onto the main design page (questions area). Once these elements are in questions area, they can be modified, edited and reordered to suit the needs of a specific survey. You can add pages to your survey by clicking the drop down menu at the top left of the page.
Detailed properties for the overall survey and each individual element can be accessed and edited by clicking the
Properties tab to the right of the page. Ordering and reordering of each survey element can be done by dragging the
hamburger glyph (three horizontal lines) to the top left of each element.
Once you have designed your survey you can test it by clicking the
Test Survey link at the top left of the page. There you will be able to choose the target device for your test (for example, if you are going to deliver the survey via iPad, choose
iPad from the drop-down list).
If you need to develop the survey in more detail via the JSON file format, you can access an editor via the
JSON Editor link at the top of the page.
Each toolbox item will have its own configuration panel once it is placed into the Survey Creator. This panel contains a set of
adorners. Using adorners, you will be able to move and re-order the item using the
hamburger button (three horizontal lines), delete the item using the
cross button, toggle the item's visibility using the
duplicate the item,
add the item to the toolbox, see the item's
mode and edit the items
properties. You may also set the item's
required status if the tool allows it.
Individual Toolbox Elements
Single Input allows you to ask a simple question or request a non-predetermined input from a respondent. A single line is presented to the respondent for text input. There are no limits on the possible input so the respondent may enter any text and any amount of text.
Checkbox allows for multiple questions or items to be asked of a respondent. The Checkbox question presents the survey respondent with a list of items with a checkbox next to each. Ticking the checkbox chooses that item. Multiple items can be checked and only those checked are recorded in the survey.
Radiogroup allows for multiple questions or items to be asked of a respondent. The respondent is presented with a list of items with a radio button next to each. Only one item may be selected from this list and only the selected item will be recorded in the survey.
A respondent is presented with a drop-down list of items. Only one of these items can be selected, and only the selected item will be recorded in the survey.
The Comment survey element asks for a non-predetermined input from a respondent. A text box is presented to the respondent. There are no limits on the possible input so the respondent may enter any text and any amount of text.
The Rating survey element asks a respondent to choose a number across the range presented. Only one value may be selected and only the selected value will be recorded in the survey.
A respondent is presented with a list of items that can be rearranged according to rank or preference. The items are rearranged by dragging the items on the page. The final rank or order of all items is recorded in the survey.
The survey respondent is presented with a series of images. One of these images can be selected and only the value associated with that image will be recorded in the survey.
- To provide a numerical output for this element, enter a numeric value for each image in the
- Images can be ascribed different values via
Multi selectto allow the survey respondent to choose more than one image
- Image sizes can be changed via
The Boolean survey element presents a respondent with a yes or no answer. The respondent's response will be recorded in the survey as
true (yes) or
The Image survey element allows an image to be uploaded or linked into the survey. There is no associated value in relation to the survey.
The HTML tool enables HTML to be added to the survey allowing for diverse formatting for text, paragraphs and the inclusion of links and images. There is no associated value in relation to the survey.
HTMLelements allow the use of the HTML programming language within the survey to add images, files for download, text with HTML formatting among other things. They can be used in conjunction with other questions, and included in
HTMLis a powerful feature and can be used in conjunction with other elements to address many text formatting questions.
- There may be security issues with
HTMLadd ons, especially if they link to external sites
namefield but not a
title. It does not need to announce itself to the respondent, however because it has a
nameit can be called within the
conditional logicof the survey.
HTMLfield is for the presentation of text and other information directly to the respondent therefore it should not require its own
- actions within the
HTMLfield (such as clicking links and downloading files) may not be recorded and tracked directly within the survey. However due to the powerful natue of
HTMLalternative tracking could be applied. The security of any external tracking would need to be considered.
The Signature Pad survey element allows respondent input to be directly drawn on screen in a pre-set box or area. This is typically used to obtain a signature from the respondent, however it could be used to obtain any hand-drawn input. The size of the box presented to the respondent may be changed by clicking on the
Properties tab. The color of the pen and background can also be changed. The input from the respondent is recorded in the survey in the following file formats: JPEG, PNG or SVG. This file format may be changed in the
The Expression survey element allows for data and calculations to be presented to a respondent. For example, this element provides functionality for adding up the scores of previous question responses, showing the current date and time for the respondent. Configuration is available via the
Properties tab; click
General then edit the
Expression text box. Examples are given:
- (*)*(100 - )
The File survey element presents a button to a respondent requesting that a file is uploaded. When the respondent presses the
Choose File button, an upload file dialogue will launch within a web browser. Many details can be specified via the
Properties tab such as maximum file size, multiple uploads, accepted file formats as well as preview area. The file(s) uploaded via the File element will be recorded/retained in the survey. File formats are restricted by a comma-separated list of file extensions including periods e.g.:
.png. The uploaded file is recorded in the survey. For security, it is important that you strictly specify the file formats that are allowed to be uploaded into the survey.
Matrix (Single Choice)
The Matrix (Single Choice) tool allows for an array of radio buttons to be presented to the survey respondent in rows and columns. The amount of rows and columns can be adjusted, however only one item per row can be selcted. Names of rows and columns can be edited via the
properties tab: Click
Columns and then
Fast Entry to type these in. The order that rows are presented to the respondent can be set to
initial (the latter will sort rows aphabetically by the first letter). Only radio buttons that have been selected will be recorded in the survey.
Textcontrols what the user sees
Valuecontrols what is made available as data and within the
conditional logicof the survey
Matrix (Multiple Choice)
The Matrix (Multiple Choice) survey element presents a survey respondent with an array of columns and rows. Each cell of the array can be configured with a list of selectable items. These selectable items can be presented to the respondent through the following cell types:
- Single Input
(Please see above for descriptions of these types of interaction)
Cell type can be changed via the
Properties tab. The amount of columns and rows, the title of rows and the value of the selectable item can also be edited via the
Properties tab. Click
Fast Entry to name each row. Click
Fast Entry to edit the item/value. To hide the name of each column, click
Layout and uncheck
Show Header. Click
Data to set the
Default Value for each cell and a
Correct Answer if desired. The respondent makes a selection and this is recorded in the survey according to three values: Row, Column and Item/value. Only those selected are recorded in the survey.
Matrix (Dynamic Rows)
The Matrix (Dynamic Rows) survey element contains the same functionality as the Matrix (Multiple Choice) element above, but adds a dynamic element that is controlled by a survey respondent. Respondents can
remove rows according to their needs. Please see the overview for the Matrix (Multiple Choice) element above for more detail about configuring this element.
The Multiple Text survey element allows for a respondent to input multiple single line inputs. See 'Single Input' above for a basic description. Multiple Text presents a stacked series of Single Input entries. The
Properties tab allows for configuration of the default value of each field (is the text field empty or does it have pre-filled text?), the amount of columns used to display the text fields as well as the overall amount of text fields/items. Only the entries that have input from the respondent are recorded in the survey.
The Panel survey element serves as a box or container that can include multiple questions and sub-panels.
Panel (Dynamic Panels)
The Panel (Dynamic Panels) tool allows you to create a template box or container element that can include multiple questions and input types. This template is activated when the survey respondent actively clicks
Add New in the survey. The respondent can activate any number of these templates by repeatedly clicking
Question Number and
Title in survey
Question Number and
Title can be hidden in the survey output.
Hide number removes the number at the start of the question while retaining your title. You can also remove the whole number and title with
Title location and set it to
Hidden. This can be useful if you are planning on using an
HTML element to ask the question or otherwise direct the survey respondent.
Formatting text within the survey
Presenting text within the survey can be partially acheived using the
Description fields of each
Element. These fields are an easy and direct way to add questions and direction to the survey respondent. While this is easy and direct, there are limitations to using these fields. For instance, the
Description field of an
Element does not allow formatting such as italics or bold. These limitations can be overcome by using an
HTML element to provide the necessary textual material for your survey.
Every survey element can be triggered by any question within the survey. This allows the
availability of each element to be conditional on the responses made elsewhere in the survey. For example,
Conditional Logic would allow for a
Matrix to appear if a
Boolean question was answered
Yes, and an
Image Picker to appear if the same
Boolean was answered
Logic within your survey makes it dynamic and responsive, and enables you to create separate pathways throughout the survey as a whole.
To define the
logic for each element, go to
Visible ifcontrols whether the element is made
Logic Expressions. If these
Expressionsare defined, then the element will remain invisible within the survey unless the conditions of the expression are met.
Enable ifcontrols whether the element is
Logic Expressions. The element will be visible, but the responses will disabled until the conditions of the expression are met.
Required ifcontrols whether the element's
Requiredstate is determined through
Logic Expressions. If an element is required, then it becomes compulsory and the survey cannot proceed or be completed unless that element has recorded a response (
Requiredstatus can also be determined manually by toggling
Naming an element for use in an
When you add a survey element you are able to give it both a
Title and a
Name in the
General section. Understanding the difference between
Name is important when developing the
Logic of your survey. In short,
Name refers to the question as a logical entity that can be refered to within the
Conditional Logic of the survey without confusion.
Title refers to text that is directed to the survey respondent and it may be unsuitable for use within the terse structure of the survey's logic.
An example of a
Name might be
Q1vegetables while the corresponding
Title might be
Please select your favourites from the following vegetables. It is clear that the purpose of the
Title is to direct the survey user, while the
Name refers to the question within the
Logic of the survey.
- If there is no
Namewill be used instead.
Namecan be hidden in the survey by setting
Hidden. This might be useful if you plan on providing a question to the survey user using the
HTMLelement, for example.
To build the
Expression for an element, go to
Logic and choose how you would like to trigger the element (for example, choose
Visible if if you would like the element to remain invisible until the conditions of the expresion are met). When you select
Visible if, you will be directed to
Select question.... This will open a drop-down dialogue that lists all available questions in the survey. The dialogue will list these by
Select the question you would like to use within the
Expression. Once selected, you will be able to select the
Operator you would like to apply to your chosen question. Operators could be:
is not empty
greater or equals
less or equals
Depending on the type of question you have chosen, only some of these
Operators may be available and others will be grayed out.
Once you have chosen the question and the
Operator, you will be able to select the state that the question must have in order to meet the requirements of the
Expression. For example, in the following image
Q2 is the question,
equals is the
Operator and the state of
Selected fulfils the requirements of the
You can also add more than one condition for your expression to meet in order to be valid. Press
Add condition to develop the
Expression further. Multiple conditions can be set and their interrelation is based on the logical
Anddetermines that the second
Expressionmust also be valid in order for the whole
Expressionto be met. In this example, we are using an expression to determine if an element is
Visible. Choosing the
Operatormeans that the element will not be visible unless the conditions of both expressions are met.
Ordetermines that the second
Expressionis an alternative to the first: either the details of the first
Expressionfulfil the conditions to make the element
Visible, or the details of the second
Expressioncan also fulfil the conditions of the
Specific use cases of
Conditional Logic will be the same across all survey elements. However there are some interesting and specific use cases.
Logic within a
Conditional logic can be set within a
Matrix element on a column-row basis. This means that you can set columns to
Enabled by setting an
Expression condition within the same row. This allows each row to have it's own conditional logic.
Logic of each specific column is set by editing the column details. Each column can be edited via
Edit, and within this there is a
Logic section specific to that column.
Once you click
Edit for a specific column, you will be shown a configuration section for that column:
Availabilityof the column can be determined by a single question anywhere within the survey, including the
Matrixthe column belongs to.
- The column can also be made
Visiblerelative to a question within the same row of the
Matrix. For example if you have a
Matrixwith four columns and you would like the
Visibilityof columns 2-4 to be triggered by a
Booleanin column 1, you will need to set the
Logicof columns 2, 3 and 4 to be
- The question
row.<columnname>refers to the
rowthat is relative to the question, then the
Namethat you have given the column. In this instance,
rowmeans 'in the current row'
- It would be necessary to apply this
Logicto all columns you would like to be affected by the trigger.
The end-result of setting logic within a
Matrix can be seen in the following images.
First, the survey only shows the
Boolean questions from column one:
Boolean from Column 1/Row 1 is set to
yes/true, which makes columns 2-4
Visible. Notice how this only applies to Row 1.
Boolean from Column 1/Row 2 is set to
yes/true, which makes columns 2-4
Visible in Row 2 as well as Row 1. Note that Columns 2-4 in Row 3 are still not
- SurveyJS Support Forums - useful for searching user questions on specific features