API Reference: Survey Data Model | Form Builder Libraries

activePage property

Returns startedPage if the survey currently displays a start page; otherwise, returns currentPage.

Type:: any readonly

Implemented in:: SurveyModel

See also:: startedPage * , currentPage * , firstPageIsStarted

addLayoutElement method

Adds an element to the survey layout.

This method accepts an object with the following layout element properties:

id: string | "timerpanel" | "progress-buttons" | "progress-questions" | "progress-pages" | "progress-correctquestions" | "progress-requiredquestions" | "toc-navigation" | "buttons-navigation"
A layout element identifier. You can use possible values to access and relocate or customize predefined layout elements.
container: "header" | "footer" | "left" | "right" | "contentTop" | "contentBottom"
A layout container that holds the element. If you want to display the element within multiple containers, set this property to an array of possible values.
component: string
The name of the component that renders the layout element.
data: any
Data passed as props to component.

View Demo

Type:: (layoutElement: ISurveyLayoutElement) => ISurveyLayoutElement

Parameters:: layoutElement, type: ISurveyLayoutElement ,
A layout element configuration.

Return Value:: The configuration of the previous layout element with the same id.

Implemented in:: SurveyModel

addNavigationItem method

Adds a custom navigation item similar to the Previous Page, Next Page, and Complete buttons. Accepts an object described in the IAction help section.

View Demo

Type:: (val: IAction) => Action

Parameters:: val, type: IAction

Implemented in:: SurveyModel

addNewPage method

Creates a new page and adds it to the survey.

If you want to switch a survey to the newly added page, assign its index to the currentPageNo property or assign the entire page to the currentPage property.

Type:: (name?: string, index?: number) => PageModel

Parameters:: name, type: string ,
A page name. If you do not specify this parameter, it will be generated automatically.

index, type: number ,
An index at which to insert the page. If you do not specify this parameter, the page will be added to the end.

Return Value:: The created and added page.

Implemented in:: SurveyModel

See also:: addPage * , createNewPage

addPage method

Adds an existing page to the survey.

Type:: (page: PageModel, index?: number) => void

Parameters:: page, type: PageModel ,
A page to add.

index, type: number ,
An index at which to insert the page. If you do not specify this parameter, the page will be added to the end.

Implemented in:: SurveyModel

See also:: addNewPage * , createNewPage

allowCompleteSurveyAutomatic property

Specifies whether to complete the survey automatically after a user answers all questions on the last page. Applies only if the goNextPageAutomatic property is true.

Default value: true

Type:: boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: True

Implemented in:: SurveyModel

See also:: `settings.autoAdvanceDelay`

allowResizeComment property

Specifies whether to display a resize handle for Long Text questions and other text areas intended for multi-line text content.

Default value: true

You can override this property for individual Long Text questions: allowResize.

Type:: boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: True

Implemented in:: SurveyModel

See also:: autoGrowComment

applyTheme method

Applies a specified theme to the survey.

Themes & Styles

Type:: (theme: ITheme) => void

Parameters:: theme, type: ITheme ,
An ITheme object with theme settings.

Implemented in:: SurveyModel

autoGrowComment property

Specifies whether to increase the height of Long Text questions and other text areas to accommodate multi-line text content.

Default value: false

You can override this property for individual Long Text questions: autoGrow.

Type:: boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: allowResizeComment

backgroundImage property

An image to display in the background of the survey or form. Accepts a base64 or URL string value.

Type:: string readonly

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: backgroundOpacity

backgroundOpacity property

A value from 0 to 1 that specifies how transparent the background image should be: 0 makes the image completely transparent, and 1 makes it opaque.

Type:: number writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: 1

Implemented in:: SurveyModel

calculatedValues property

An array of calculated values.

Type:: CalculatedValue[] writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

cancelPreview method

Cancels a preview of given answers and switches the survey to the page specified by the currentPage parameter.

Type:: (currentPage?: any) => void

Parameters:: currentPage, type: any ,
A new current page. If you do not specify this parameter, the survey displays the last page.

Implemented in:: SurveyModel

See also:: showPreview * , showPreviewBeforeComplete * , state

checkErrorsMode property

Specifies when the survey validates answers.

Possible values:

"onNextPage" (default) - Triggers validation before the survey is switched to the next page or completed.
"onValueChanged" - Triggers validation each time a question value is changed.
"onComplete" - Triggers validation when a user clicks the Complete button. If previous pages contain errors, the survey switches to the page with the first error.

Refer to the following help topic for more information: Data Validation.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: onNextPage

Accepted values:: onNextPage , onValueChanged , onComplete

Implemented in:: SurveyModel

See also:: validationEnabled * , validationAllowSwitchPages * , validationAllowComplete * , validate

chooseFiles method

Opens a dialog window for users to select files.

Type:: (input: HTMLInputElement, callback: (files: any[]) => void, context?: { element: Base; item?: any; elementType?: string; propertyName?: string; }) => void

Parameters:: input, type: HTMLInputElement ,
A file input HTML element.

callback, type: (files: any[]) => void ,
A callback function that you can use to process selected files. Accepts an array of JavaScript File objects.

context, type: { element: Base; item?: any; elementType?: string; propertyName?: string; }

Implemented in:: SurveyModel

See also:: onOpenFileChooser * , onUploadFile

clear method

Resets the survey state and, optionally, data. If state is "completed", it becomes "running".

Type:: (clearData?: boolean, goToFirstPage?: boolean) => void

Parameters:: clearData, type: boolean ,
(Optional) Specifies whether to clear survey data. Default value: true.

goToFirstPage, type: boolean ,
(Optional) Specifies whether to switch the survey to the first page. Default value: true.

Implemented in:: SurveyModel

clearIncorrectValues method

Removes values that cannot be assigned to a question, for example, choices unlisted in the choices array.

Call this method after you assign new question values in code to ensure that they are acceptable.

This method does not remove values that fail validation. Call the validate() method to validate newly assigned values.

Type:: (removeNonExistingRootKeys?: boolean) => void

Parameters:: removeNonExistingRootKeys, type: boolean ,
Pass true to remove values that do not correspond to any question or calculated value.

Implemented in:: SurveyModel

clearInvisibleValues property

Specifies when to remove values of invisible questions from survey results.

Possible values:

"onComplete" (default) - Clears invisible question values when the survey is complete.
"onHidden" - Clears a question value when the question becomes invisible. If the question is invisible initially, its value is removed on survey completion.
"onHiddenContainer" - Clears a question value when the question or its containter (page or panel) becomes invisible. If the question is invisible initially, its value is removed on survey completion.
"none" - Keeps invisible values in survey results.
true - Equivalent to "onComplete".
false - Equivalent to "none".

Type:: any writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: onComplete

Accepted values:: none , onComplete , onHidden , onHiddenContainer

Implemented in:: SurveyModel

See also:: Conditional Visibility , onComplete

clearValue method

Deletes an answer from survey results.

Type:: (name: string) => void

Parameters:: name, type: string ,
An object property that stores the answer to delete. Pass a question's valueName or name.

Implemented in:: SurveyModel

clearValueOnDisableItems property

Specifies whether to remove disabled choices from the value in Dropdown, Checkboxes, and Radio Button Group questions.

Default value: false

This property cannot be specified in the survey JSON schema. Use dot notation to specify it.

Type:: boolean writable

Implemented in:: SurveyModel

clientId property

A user identifier (e-mail or other unique ID).

If your application works with SurveyJS Service, the ID ensures that users do not pass the same survey twice. On the second run, they will see the Completed Before page.

Type:: string writable

Implemented in:: SurveyModel

See also:: cookieName

clone method

Creates a new object that has the same type and properties as the current SurveyJS object.

Type:: () => Base

Implemented in:: Base

comments property

An object with all comment values.

Type:: any readonly

Implemented in:: SurveyModel

See also:: Question.showCommentArea * , storeOthersAsComment

commentSuffix property

A suffix added to the name of the property that stores comments.

Default value: "-Comment"

Many question types allow respondents to leave comments. To enable this functionality, set a question's showCommentArea property to true. Comment values are saved in a separate property. The property name is composed of the question name and commentSuffix.

Respondents can also leave comments when they select "Other" in choice-based questions, such as Dropdown or Checkboxes. The property name for the comment value is composed according to the same rules. However, you can use the question name as a key to store the comment value instead. Disable the storeOthersAsComment property in this case.

View Demo

Type:: string writable

Implemented in:: SurveyModel

completedBeforeHtml property

HTML content displayed to a user who has completed the survey before. To identify such users, the survey uses a cookie name or client ID.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: processedCompletedBeforeHtml

completedHtml property

HTML content displayed on the complete page.

View Demo

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: showCompletedPage * , completedHtmlOnCondition

completedHtmlOnCondition property

An array of objects that allows you to specify different HTML content for the complete page.

Each object should include the expression and html properties. When expression evaluates to true, the survey uses the corresponding HTML markup instead of completedHtml. Refer to the following help topic for more information about expressions: Expressions.

View Demo

Type:: HtmlConditionItem[] writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

completeLastPage method

Completes the survey if it currently displays the last page and the page contains no validation errors. If both these conditions are met, this method returns true; otherwise, false.

If you want to complete the survey regardless of the current page and validation errors, use the doComplete() event.

Type:: () => boolean

Implemented in:: SurveyModel

See also:: isCurrentPageValid * , nextPage

completeText property

Gets or sets a caption for the Complete button.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: Localization & Globalization

cookieName property

A cookie name used to save information about survey completion.

When this property has a value, the survey creates a cookie with the specified name on completion. This cookie helps ensure that users do not pass the same survey twice. On the second run, they will see the Completed Before page.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: clientId

createNewPage method

Creates and returns a new page but does not add it to the survey.

Call the addPage(page) method to add the created page to the survey later or the addNewPage(name, index) method to create and add a page to the survey.

Type:: (name: string) => PageModel

Parameters:: name, type: string

Implemented in:: SurveyModel

See also:: addPage * , addNewPage

css property

Gets or sets an object in which keys are UI elements and values are CSS classes applied to them.

View Demo

Type:: any writable

Implemented in:: SurveyModel

currentPage property

Gets or sets the current page.

If you want to change the current page, set this property to a PageModel object. You can get this object in different ways. For example, you can call the getPageByName() method to obtain a PageModel object with a specific name:

survey.currentPage = survey.getPageByName("my-page-name");

Alternatively, you can change the current page if you set the currentPageNo property to the index of the required page.

The currentPage property does not return the start page even if it is current. Use the activePage property instead if your survey contains a start page.

Type:: any writable

Implemented in:: SurveyModel

currentPageNo property

A zero-based index of the current page in the visiblePages array.

View Demo

Type:: number writable

Implemented in:: SurveyModel

See also:: visiblePages

data property

Gets or sets an object with survey results. You can set this property with an object of the following structure:

{
  question1Name: question1Value,
  question2Name: question2Value,
  // ...
}

When you set this property in code, the new object overrides the old object that may contain default question values and entered data. If you want to merge the new and old objects, call the mergeData(newDataObj) method.

If you assign a new object while a respondent takes the survey, set the currentPageNo property to 0 to start the survey from the beginning. This will also cause the survey to re-evaluate the visibleIf, enableIf, and other expressions.

Type:: any writable

Implemented in:: SurveyModel

See also:: setValue * , getValue

deleteCookie method

Deletes a cookie with a specified cookieName from the browser.

Type:: () => void

Implemented in:: SurveyModel

See also:: hasCookie * , setCookie

description property

Explanatory text displayed under the title.

Type:: string writable

Implemented in:: SurveyElementCore

See also:: hasDescription

dispose method

Disposes of the survey model.

Call this method to release resources if your application contains multiple survey models or if you re-create a survey model at runtime.

Type:: () => void

Implemented in:: SurveyModel

doComplete method

Completes the survey.

When you call this method, Form Library performs the following actions:

Saves a cookie if the cookieName property is set.
Switches the survey state to "completed".
Raises the onComplete event.
Navigates the user to a URL specified by the navigateToUrl or navigateToUrlOnCondition property.
Calls the sendResult() method if Form Library works with SurveyJS Service.

The doComplete() method completes the survey regardless of validation errors and the current page. If you need to ensure that survey results are valid and full, call the completeLastPage() method instead.

Type:: (isCompleteOnTrigger?: boolean, completeTrigger?: Trigger) => boolean

Parameters:: isCompleteOnTrigger, type: boolean ,
For internal use.

completeTrigger, type: Trigger ,
For internal use.

Return Value:: false if survey completion is cancelled within the onCompleting event handler; otherwise, true.

Implemented in:: SurveyModel

See also:: surveyPostId

downloadFile method

Downloads a file from a server.

The following code shows how to call this method:

const question = survey.getQuestionByName("myFileQuestion");
survey.downloadFile(
  question,
  question.name,
  // Download the first uploaded file
  question.value[0],
  (status, data) => {
    if (status === "success") {
      // Use `data` to retrieve the file
    }
    if (status === "error") {
      // Handle error
    }
  }
);

Type:: (question: QuestionFileModel, questionName: string, fileValue: any, callback: (status: string, data: any) => any) => void

Parameters:: question, type: QuestionFileModel ,
A File Upload question instance.

questionName, type: string ,
The File Upload question's name.

fileValue, type: any ,
An object from File Upload's value array. This object contains metadata about the file you want to download.

callback, type: (status: string, data: any) => any ,
A callback function that allows you to get the download status ("success" or "error") and the file identifier (URL, file name, etc.) that you can use to retrieve the file.

Implemented in:: SurveyModel

See also:: onDownloadFile * , uploadFiles

editText property

Gets or sets a caption for the Edit button displayed when the survey shows a preview of given answers.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: showPreviewBeforeComplete * , cancelPreview * , previewText

emptySurveyText property

A message that is displayed when a survey does not contain visible pages or questions.

Type:: string writable

Implemented in:: SurveyModel

See also:: Localization & Globalization

firstPageIsStarted property

Gets or sets a Boolean value that specifies whether the first page is a start page.

Refer to the following help topic for more information: Start Page.

Type:: boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: startedPage * , activePage

focusFirstQuestion method

Focuses the first question on the current page.

Type:: () => void

Implemented in:: SurveyModel

See also:: focusQuestion * , focusFirstQuestionAutomatic

focusFirstQuestionAutomatic property

Specifies whether to focus the first question on the page on survey startup or when users switch between pages.

Default value: false in v1.9.114 and later, true in earlier versions

Type:: boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: focusOnFirstError * , focusFirstQuestion * , focusQuestion

focusOnFirstError property

Specifies whether to focus the first question with a validation error on the current page.

Default value: true

Type:: boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: True

Implemented in:: SurveyModel

See also:: validate * , focusFirstQuestionAutomatic

focusQuestion method

Focuses a question with a specified name. Switches the current page if needed.

Type:: (name: string) => boolean

Parameters:: name, type: string ,
A question name.

Return Value:: false if the survey does not contain a question with a specified name or this question is hidden; otherwise, true.

Implemented in:: SurveyModel

See also:: focusFirstQuestion * , focusFirstQuestionAutomatic

fromJSON method

Assigns a new configuration to the current SurveyJS object. This configuration is taken from a passed JSON object.

The JSON object should contain only serializable properties of this SurveyJS object. Event handlers and properties that do not belong to the SurveyJS object are ignored.

Type:: (json: any, options?: ILoadFromJSONOptions) => void

Parameters:: json, type: any ,
A JSON object with properties that you want to apply to the current SurveyJS object.

options, type: ILoadFromJSONOptions ,
An object with configuration options.

Implemented in:: Base

See also:: toJSON

getAllPanels method

Returns a list of all panels in the survey.

Type:: (visibleOnly?: boolean, includeDesignTime?: boolean) => IPanel[]

Parameters:: visibleOnly, type: boolean ,
A Boolean value that specifies whether to include only visible panels.

includeDesignTime, type: boolean ,
For internal use.

Return Value:: An array of panels.

Implemented in:: SurveyModel

See also:: getPanelByName

getAllQuestions method

Returns a list of all questions in the survey.

Type:: (visibleOnly?: boolean, includeDesignTime?: boolean, includeNested?: boolean) => Question[]

Parameters:: visibleOnly, type: boolean ,
A Boolean value that specifies whether to include only visible questions.

includeDesignTime, type: boolean ,
For internal use.

includeNested, type: boolean ,
A Boolean value that specifies whether to include nested questions, such as questions within matrix cells.

Return Value:: An array of questions.

Implemented in:: SurveyModel

See also:: getQuestionByName

getComment method

Returns a comment value from a question with a specified name.

Type:: (name: string) => string

Parameters:: name, type: string ,
A question name.

Return Value:: A comment.

Implemented in:: SurveyModel

See also:: setComment

getCorrectAnswerCount method

Returns the number of correct answers in a quiz.

For more information about quizzes, refer to the following tutorial: Create a Quiz.

Type:: () => number

Return Value:: The number of correct answers in a quiz.

Implemented in:: SurveyModel

See also:: getQuizQuestionCount * , getInCorrectAnswerCount

getInCorrectAnswerCount method

Returns the number of incorrect answers in a quiz.

For more information about quizzes, refer to the following tutorial: Create a Quiz.

Type:: () => number

Return Value:: The number of incorrect answers in a quiz.

Implemented in:: SurveyModel

See also:: getCorrectAnswerCount

getPageByElement method

Returns a page to which a specified survey element (question or panel) belongs.

Type:: (element: IElement) => PageModel

Parameters:: element, type: IElement ,
A question or panel instance.

Implemented in:: SurveyModel

getPageByName method

Returns a page with a specified name.

Type:: (name: string) => PageModel

Parameters:: name, type: string ,
A page name.

Implemented in:: SurveyModel

getPageByQuestion method

Returns a page to which a specified question belongs.

Type:: (question: IQuestion) => PageModel

Parameters:: question, type: IQuestion ,
A question instance.

Implemented in:: SurveyModel

getPagesByNames method

Returns an array of pages with specified names.

Type:: (names: string[]) => PageModel[]

Parameters:: names, type: string[] ,
An array of page names.

Implemented in:: SurveyModel

getPanelByName method

Returns a panel with a specified name.

Type:: (name: string, caseInsensitive?: boolean) => PanelModel

Parameters:: name, type: string ,
A panel name.

caseInsensitive, type: boolean ,
(Optional) A Boolean value that specifies case sensitivity when searching for the panel. Default value: false (uppercase and lowercase letters are treated as distinct).

Return Value:: A panel with a specified name.

Implemented in:: SurveyModel

See also:: getAllPanels

getPlainData method

Returns survey results as an array of objects in which the question name, title, value, and other parameters are stored as individual properties.

If a question can have more than one value (Matrix, Multiple Text), its object enables the isNode flag and stores information about these values in the data property. Refer to the following help topic for more information: Access Full Survey Results.

If you want to skip empty answers, pass an object with the includeEmpty property set to false.

Type:: (options?: IPlainDataOptions) => IQuestionPlainData[]

Parameters:: options, type: IPlainDataOptions

Implemented in:: SurveyModel

getPropertyByName method

Returns a JsonObjectProperty object with metadata about a serializable property that belongs to the current SurveyJS object.

If the property is not found, this method returns null.

Type:: (propName: string) => JsonObjectProperty

Parameters:: propName, type: string ,
A property name.

Implemented in:: Base

getPropertyValue method

Returns the value of a property with a specified name.

If the property is not found or does not have a value, this method returns either undefined, defaultValue specified in the property configuration, or a value passed as the defaultValue parameter.

Type:: (name: string, defaultValue?: any) => any

Parameters:: name, type: string ,
A property name.

defaultValue, type: any ,
(Optional) A value to return if the property is not found or does not have a value.

Implemented in:: Base

getQuestionByName method

Returns a question with a specified name.

Type:: (name: string, caseInsensitive?: boolean) => Question

Parameters:: name, type: string ,
A question name

caseInsensitive, type: boolean ,
(Optional) A Boolean value that specifies case sensitivity when searching for the question. Default value: false (uppercase and lowercase letters are treated as distinct).

Return Value:: A question with a specified name.

Implemented in:: SurveyModel

See also:: getAllQuestions * , getQuestionByValueName

getQuestionByValueName method

Returns a question with a specified valueName.

Since valueName does not have to be unique, multiple questions can have the same valueName value. In this case, the getQuestionByValueName() method returns the first such question. If you need to get all questions with the same valueName, call the getQuestionsByValueName() method.

Type:: (valueName: string, caseInsensitive?: boolean) => Question

Parameters:: valueName, type: string ,
A question's valueName property value.

caseInsensitive, type: boolean ,
(Optional) A Boolean value that specifies case sensitivity when searching for the question. Default value: false (uppercase and lowercase letters are treated as distinct).

Return Value:: A question with a specified valueName.

Implemented in:: SurveyModel

See also:: getAllQuestions * , getQuestionByName

getQuestionsByNames method

Returns an array of questions with specified names.

Type:: (names: string[], caseInsensitive?: boolean) => IQuestion[]

Parameters:: names, type: string[] ,
An array of question names.

caseInsensitive, type: boolean ,
(Optional) A Boolean value that specifies case sensitivity when searching for the questions. Default value: false (uppercase and lowercase letters are treated as distinct).

Return Value:: An array of questions with specified names

Implemented in:: SurveyModel

See also:: getAllQuestions

getQuestionsByValueName method

Returns all questions with a specified valueName. If a question's valueName is undefined, its name property is used.

Type:: (valueName: string, caseInsensitive?: boolean) => Question[]

Parameters:: valueName, type: string ,
A question's valueName property value.

caseInsensitive, type: boolean ,
(Optional) A Boolean value that specifies case sensitivity when searching for the questions. Default value: false (uppercase and lowercase letters are treated as distinct).

Return Value:: An array of questions with a specified valueName.

Implemented in:: SurveyModel

See also:: getAllQuestions * , getQuestionByName

getQuizQuestionCount method

Returns the number of quiz questions. A question counts if it is visible, has an input field, and specifies correctAnswer.

This number may be different from getQuizQuestions().length because certain question types (for instance, matrix-like types) include more than one question.

For more information about quizzes, refer to the following tutorial: Create a Quiz.

Type:: () => number

Return Value:: The number of quiz questions.

Implemented in:: SurveyModel

See also:: getQuizQuestions

getQuizQuestions method

Returns an array of quiz questions. A question counts if it is visible, has an input field, and specifies correctAnswer.

For more information about quizzes, refer to the following tutorial: Create a Quiz.

Type:: () => IQuestion[]

Return Value:: An array of quiz questions.

Implemented in:: SurveyModel

See also:: getQuizQuestionCount

getResult method

Requests SurveyJS Service to retrieve all answers to a specified question. Handle the onGetResult event to access the answers.

Type:: (resultId: string, questionName: string) => void

Parameters:: resultId, type: string ,
A result ID that identifies the required survey. You can find it on the My Surveys page.

questionName, type: string ,
A question name.

Implemented in:: SurveyModel

getType method

Returns the object type as it is used in the JSON schema.

Type:: () => string

Implemented in:: Base

getUsedLocales method

Returns an array of locales whose translations are used in the survey.

Localization & Globalization help topic

Survey Localization demo

Type:: () => string[]

Implemented in:: SurveyModel

getValue method

Returns a value (answer) for a question with a specified name.

Type:: (name: string) => any

Parameters:: name, type: string ,
A question name.

Return Value:: A question value (answer).

Implemented in:: SurveyModel

See also:: data * , setValue

getVariable method

Returns a variable value.

Variables help topic

Type:: (name: string) => any

Parameters:: name, type: string ,
A variable name.

Implemented in:: SurveyModel

See also:: setVariable * , getVariableNames

getVariableNames method

Returns the names of all variables in the survey.

Variables help topic

Type:: () => string[]

Return Value:: An array of variable names.

Implemented in:: SurveyModel

See also:: getVariable * , setVariable

goNextPageAutomatic property

Specifies whether the survey switches to the next page automatically after a user answers all questions on the current page.

Default value: false

If you enable this property, the survey is also completed automatically. Set the allowCompleteSurveyAutomatic property to false if you want to disable this behavior.

If any of the following questions is answered last, the survey does not switch to the next page: Checkboxes, Yes/No (Boolean) (rendered as Checkbox), Long Text, Signature, Image Picker (with Multi Select), File Upload, Single-Select Matrix (not all rows are answered), Dynamic Matrix, Dynamic Panel.

View Demo

Type:: boolean | "autogonext" writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: `settings.autoAdvanceDelay`

hasCookie property

Indicates whether the browser has a cookie with a specified cookieName. If this property's value is true, the respondent has passed the survey previously.

Type:: boolean readonly

Implemented in:: SurveyModel

See also:: setCookie * , deleteCookie

hasDescription property

Returns true if the survey element has a description.

Type:: boolean readonly

Implemented in:: SurveyElementCore

See also:: description

headerView property

This property is obsolete. Use the headerView property within a theme instead.

Type:: "advanced" | "basic" readonly

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: basic

Accepted values:: basic , advanced

Implemented in:: SurveyModel

hideRequiredErrors property

Specifies whether to hide validation errors thrown by the Required validation in the UI.

Built-In Client-Side Validators

Type:: boolean readonly

Implemented in:: SurveyModel

See also:: validationEnabled * , validationAllowSwitchPages

ignoreValidation property

This property is obsolete. Use the validationEnabled property instead.

Type:: boolean writable

Implemented in:: SurveyModel

inSurvey property

Returns true if the object is included in a survey.

This property may return false, for example, when you create a survey model dynamically.

Type:: boolean readonly

Implemented in:: Base

isCurrentPageValid property

Returns true if the current page does not contain errors.

Type:: boolean readonly

Implemented in:: SurveyModel

See also:: currentPage

isDescendantOf method

Use this method to find out if the current object is of a given typeName or inherited from it.

Type:: (typeName: string) => boolean

Parameters:: typeName, type: string ,
One of the values listed in the getType() description.

Return Value:: true if the current object is of a given typeName or inherited from it.

Implemented in:: Base

See also:: getType

isDesignMode property

Indicates whether the survey is being designed in Survey Creator.

Type:: boolean readonly

Implemented in:: SurveyModel

isEmpty property

Returns true if the survey contains zero pages.

Type:: boolean readonly

Implemented in:: SurveyModel

See also:: emptySurveyText

isFirstPage property

Indicates whether the current page is the first page.

If the survey displays the start page, this property contains false. Use the isShowStartingPage property to find out whether the start page is currently displayed.

Type:: boolean readonly

Implemented in:: SurveyModel

isLastPage property

Indicates whether the current page is the last page.

Type:: boolean readonly

Implemented in:: SurveyModel

isLoadingFromJson property

Returns true if the object configuration is being loaded from JSON.

Type:: boolean readonly

Implemented in:: Base

isShowStartingPage property

A Boolean value that indicates whether the start page is currently displayed.

Type:: boolean readonly

Implemented in:: SurveyModel

isValidatingOnServer property

Indicates whether the current page is being validated on a server.

Type:: boolean readonly

Implemented in:: SurveyModel

isValueEmpty method

Returns true if a passed value is an empty string, array, or object or if it equals to undefined or null.

Type:: (value: any, trimString?: boolean) => boolean

Parameters:: value, type: any ,
A value to be checked.

trimString, type: boolean ,
(Optional) When this parameter is true, the method ignores whitespace characters at the beginning and end of a string value. Pass false to disable this functionality.

Implemented in:: Base

jsonErrors property

A list of errors in a survey JSON schema.

Type:: JsonError[] readonly

Implemented in:: SurveyModel

See also:: ensureUniqueNames

keepIncorrectValues property

Specifies whether to keep values that cannot be assigned to questions, for example, choices unlisted in the choices array.

This property cannot be specified in the survey JSON schema. Use dot notation to specify it.

Type:: boolean writable

Implemented in:: SurveyModel

See also:: clearIncorrectValues

lazyRendering property

Specifies whether to enable lazy rendering.

In default mode, a survey renders the entire current page. With lazy rendering, the survey renders the page gradually as a user scrolls it. This helps reduce survey startup time and optimizes large surveys for low-end devices.

Default value: false

View Demo

Type:: boolean writable

Implemented in:: SurveyModel

See also:: settings.lazyRender

loadingHtml property

HTML content displayed while a survey JSON schema is being loaded from SurveyJS Service.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: surveyId * , processedLoadingHtml

loadSurveyFromService method

Loads a survey JSON schema from the SurveyJS Service. You can handle the onLoadedSurveyFromService event to modify the schema after loading if required.

Type:: (surveyId?: string, clientId?: string) => void

Parameters:: surveyId, type: string ,
The identifier of a survey JSON schema to load. Refer to the following help topic for more information: Store Survey Results in the SurveyJS Service.

clientId, type: string ,
A user identifier (e-mail or other unique ID) used to determine whether the user has already taken the survey.

Implemented in:: SurveyModel

locale property

Specifies the survey's locale.

Default value: "" (a default locale is used)

Localization & Globalization help topic

Survey Localization demo

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Accepted values:

Implemented in:: SurveyModel

logo property

An image URL or a Base64-encoded image to use as a survey logo.

View Demo

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: logoPosition * , logoFit

logoFit property

Specifies how to resize a logo to fit it into its container.

Possible values:

"contain" (default)
"cover"
"fill"
"none"

Refer to the object-fit CSS property description for information on the possible values.

View Demo

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: contain

Accepted values:: none , contain , cover , fill

Implemented in:: SurveyModel

See also:: logo * , logoPosition

logoHeight property

A logo height in CSS-accepted values.

Default value: 200px

View Demo

Type:: any writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: 200px

Implemented in:: SurveyModel

See also:: logoHeight * , logo * , logoPosition * , logoFit

logoPosition property

A logo position relative to the survey title.

Possible values:

"left" (default) - Places the logo to the left of the survey title.
"right" - Places the logo to the right of the survey title.
"none" - Hides the logo.

View Demo

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: left

Accepted values:: none , left , right , top , bottom

Implemented in:: SurveyModel

See also:: logo * , logoFit

logoWidth property

A logo width in CSS-accepted values.

Default value: 300px

View Demo

Type:: any writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: 300px

Implemented in:: SurveyModel

See also:: logoHeight * , logo * , logoPosition * , logoFit

matrixDragHandleArea property

Specifies which part of a matrix row responds to a drag gesture in Dynamic Matrix questions.

Possible values:

"entireItem" (default) - Users can use the entire matrix row as a drag handle.
"icon" - Users can only use a drag icon as a drag handle.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: entireItem

Accepted values:: entireItem , icon

Implemented in:: SurveyModel

maxOthersLength property

Specifies the maximum text length for question comments. Applies to questions with the showCommentArea or showOtherItem property set to true.

Default value: 0 (unlimited)

Type:: number writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: maxTextLength

maxTextLength property

Specifies the maximum text length in textual questions (Single-Line Input, Long Text, Multiple Textboxes), measured in characters.

Default value: 0 (unlimited)

You can override this setting for individual questions if you specify their maxLength property.

Type:: number writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: maxOthersLength

maxTimeToFinish property

A time period that a respondent has to complete the survey; measured in seconds. Applies only to quiz surveys.

A negative value or 0 sets an unlimited time period.

View Demo

Type:: number writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: maxTimeToFinishPage * , startTimer * , timeSpent

maxTimeToFinishPage property

A time period that a respondent has to complete each survey page; measured in seconds. Applies only to quiz surveys.

A negative value or 0 sets an unlimited time period.

You can also use PageModel's maxTimeToFinish property to specify a time period for an individual survey page.

View Demo

Type:: number writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: maxTimeToFinish * , startTimer * , timeSpent

mergeData method

Merges a specified data object with the object from the data property.

Refer to the following help topic for more information: Populate Form Fields | Multiple Question Values.

Type:: (data: any) => void

Parameters:: data, type: any ,
A data object to merge. It should have the following structure: { questionName: questionValue, ... }

Implemented in:: SurveyModel

See also:: setValue

mode property

Specifies whether users can take the survey or only view it.

Possible values:

"edit" (default) - Allows users to take the survey.
"display" - Makes the survey read-only.

View Demo

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: edit

Accepted values:: edit , display

Implemented in:: SurveyModel

navigateToUrl property

A URL to which respondents should be navigated after survey completion.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: onNavigateToUrl * , navigateToUrlOnCondition

navigateToUrlOnCondition property

An array of objects that allows you to navigate respondents to different URLs after survey completion.

Each object should include the expression and url properties. When expression evaluates to true, the survey navigates to the corresponding url. Refer to the following help topic for more information about expressions: Expressions.

Type:: UrlConditionItem[] writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: onNavigateToUrl * , navigateToUrl

nextPage method

Switches the survey to the next page.

This method returns a Boolean value that indicates whether the page was successfully switched. false is returned if the current page is the last page or if it contains validation errors.

Type:: () => boolean

Return Value:: true if the page was successfully switched; false otherwise.

Implemented in:: SurveyModel

See also:: isLastPage * , prevPage * , completeLastPage

notify method

Displays a toast notification with a specified message.

Depending on the type argument, a survey can display the following notification types:

Toast notification types in SurveyJS Form Library

Type:: (message: string, type: string, showActions?: boolean) => void

Parameters:: message, type: string ,
A message to display.

type, type: string ,
A notification type: "info" (default), "success", or "error".

showActions, type: boolean ,
For internal use.

Implemented in:: SurveyModel

onAfterRenderHeader event

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.htmlElement: HTMLElement
A rendered HTML element.

Type:: EventBase<SurveyModel, AfterRenderHeaderEvent>

Implemented in:: SurveyModel

onAfterRenderMatrixCell event

An event that is raised for every matrix cell after it is rendered to the DOM.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.htmlElement: HTMLElement
A rendered HTML element.
options.cell: MatrixDropdownCell
A matrix cell for which the event is raised.
options.cellQuestion: Question
A Question instance within the matrix cell.
options.row: MatrixDropdownRowModelBase
A matrix row to which the cell belongs.
options.column: MatrixDropdownColumn | MatrixDropdownCell
A matrix column to which the cell belongs.

Type:: EventBase<SurveyModel, MatrixAfterCellRenderEvent>

Implemented in:: SurveyModel

See also:: onMatrixCellCreated

onAfterRenderPage event

An event that is raised after a page is rendered to the DOM. Use it to modify page markup.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.htmlElement: HTMLElement
A rendered HTML element.
options.page: PageModel
A Page instance for which the event is raised.

View Demo

Type:: EventBase<SurveyModel, AfterRenderPageEvent>

Implemented in:: SurveyModel

onAfterRenderPanel event

An event that is raised after a panel is rendered to the DOM. Use it to modify panel markup.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.htmlElement: HTMLElement
A rendered HTML element.
options.panel: PanelModel
A Panel instance for which the event is raised.

This event is raised for static Panels as well as panels within a Dynamic Panel.

Type:: EventBase<SurveyModel, AfterRenderPanelEvent>

Implemented in:: SurveyModel

onAfterRenderQuestion event

An event that is raised after a question is rendered to the DOM. Use it to modify question markup.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.htmlElement: HTMLElement
A rendered HTML element.

View Demo

Type:: EventBase<SurveyModel, AfterRenderQuestionEvent>

Implemented in:: SurveyModel

onAfterRenderQuestionInput event

An event that is raised after a question with a single input field is rendered to the DOM. Use it to modify question markup.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.htmlElement: HTMLElement
A rendered HTML element.

This event is not raised for questions without input fields (HTML, Image) or questions with multiple input fields (Matrix, Multiple Text).

Type:: EventBase<SurveyModel, AfterRenderQuestionInputEvent>

Implemented in:: SurveyModel

onAfterRenderSurvey event

An event that is raised after the survey is rendered to the DOM. Use this event to modify survey markup.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.htmlElement: HTMLElement
A rendered HTML element.

View Demo

Type:: EventBase<SurveyModel, AfterRenderSurveyEvent>

Implemented in:: SurveyModel

onChoicesLazyLoad event

Use this event to load choice items in Dropdown and Tag Box questions on demand.

This event is raised only for those questions that have the choicesLazyLoadEnabled property set to true.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.setItems: (items: (string | { value: any; text?: String; imageLink?: string; customProperty?: any; })[], totalCount: number) => void
A method that you should call to assign loaded items to the question. Item objects should be structured as specified in the choices property description. If their structure is different, map their properties to bring them to the required structure.
options.filter: string
A search string used to filter choices.
options.take: number
The number of choice items to load. You can use the question's choicesLazyLoadPageSize property to change this number.
options.skip: number
The number of choice items to skip.

View Demo

Type:: EventBase<SurveyModel, ChoicesLazyLoadEvent>

Implemented in:: SurveyModel

onChoicesSearch event

An event that is raised each time a search string in a Dropdown or Tag Box question changes. Use this event to implement custom filtering of choice options.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.filter: string
A search string used to filter choice options.
options.choices: ItemValue[]
An array of all choice options.
options.filteredChoices: ItemValue[]
A filtered array of choice options. Apply options.filter to the options.choices array and assign the result to this parameter.

Type:: EventBase<SurveyModel, ChoicesSearchEvent>

Implemented in:: SurveyModel

See also:: QuestionDropdownModel.searchEnabled , QuestionDropdownModel.searchMode

onClearFiles event

An event that is raised when users clear files in a File Upload question or clear signature in a Signature Pad question. Use this event to delete files from your server.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionFileModel | QuestionSignaturePadModel
A File Upload or Signature Pad question instance for which the event is raised.
options.name: string
A File Upload question's name.
options.callback: (status: string, data?: any) => any
A callback function that you should call when files are deleted successfully or when deletion fails. Pass "success" or "error" as the first argument to indicate the operation status. As the second argument, you can pass deleted files' data (options.value) if file deletion was successful or an error message if file deletion failed.
options.fileName: string
The name of a file to delete. When this parameter is null, all files should be deleted.
options.value: any
The File Upload question's value that contains metadata about uploaded files.

View Demo

Type:: EventBase<SurveyModel, ClearFilesEvent>

Implemented in:: SurveyModel

See also:: clearFiles * , onDownloadFile * , onUploadFiles

onComplete event

An event that is raised after the survey is completed. Use this event to send survey results to the server.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.isCompleteOnTrigger: boolean
Returns true if survey completion is caused by a "complete" trigger.
options.completeTrigger: Trigger
A "complete" trigger that has been executed. This parameter has a value only if options.isCompleteOnTrigger is true.
options.clearSaveMessages: (test?: string) => void
Call this method to hide the save operation messages.
options.showSaveSuccess: (text?: string) => void
Call this method to indicate that survey results are successfully saved. You can use the text parameter to display a custom message.
options.showSaveError: (text?: string) => void
Call this method to indicate that an error occurred during the save operation. You can use the text parameter to display a custom error message.
options.showSaveInProgress: (text?: string) => void
Call this method to indicate that the save operation is in progress. You can use the text parameter to display a custom message.

For an example of how to use the methods described above, refer to the following help topic: Store Survey Results in Your Own Database.

Do not disable the showCompletedPage property if you call one of the options.showSave... methods. This is required because the UI that indicates data saving progress is integrated into the complete page. If you hide the complete page, the UI also becomes invisible.

Type:: EventBase<SurveyModel, CompleteEvent>

Implemented in:: SurveyModel

See also:: onPartialSend * , doComplete * , allowCompleteSurveyAutomatic

onCompleting event

An event that is raised before the survey is completed. Use this event to prevent survey completion.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.isCompleteOnTrigger: boolean
Returns true if survey completion is caused by a "complete" trigger.
options.completeTrigger: Trigger
A "complete" trigger that has been executed. This parameter has a value only if options.isCompleteOnTrigger is true.
options.allow: boolean
A Boolean property that you can set to false if you want to prevent survey completion.

Type:: EventBase<SurveyModel, CompletingEvent>

Implemented in:: SurveyModel

See also:: onComplete * , doComplete * , allowCompleteSurveyAutomatic

onCurrentPageChanged event

An event that is raised after the current page is switched.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.isPrevPage: boolean
Returns true if the respondent is switching to the previous page.
options.isNextPage: boolean
Returns true if the respondent is switching to the next page.
options.isGoingBackward: boolean
Returns true if the respondent is going backward, that is, newCurrentPage is earlier in the survey than oldCurrentPage.
options.isGoingForward: boolean
Returns true if the respondent is going forward along the survey.
options.isAfterPreview: boolean
Returns true if the respondent is switching from the preview page.
options.newCurrentPage: PageModel
The current page.
options.oldCurrentPage: PageModel
A page that used to be current.

Type:: EventBase<SurveyModel, CurrentPageChangedEvent>

Implemented in:: SurveyModel

See also:: currentPageNo * , nextPage * , prevPage

onCurrentPageChanging event

An event that is raised before the current page is switched.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.isPrevPage: boolean
Returns true if the respondent is switching to the previous page.
options.isNextPage: boolean
Returns true if the respondent is switching to the next page.
options.isGoingBackward: boolean
Returns true if the respondent is going backward, that is, newCurrentPage is earlier in the survey than oldCurrentPage.
options.isGoingForward: boolean
Returns true if the respondent is going forward along the survey.
options.isAfterPreview: boolean
Returns true if the respondent is switching from the preview page.
options.newCurrentPage: PageModel
The current page.
options.oldCurrentPage: PageModel
A page that used to be current.
options.allow: boolean
A Boolean property that you can set to false if you do not want to switch the current page.

Type:: EventBase<SurveyModel, CurrentPageChangingEvent>

Implemented in:: SurveyModel

See also:: currentPageNo * , nextPage * , prevPage **

onDownloadFile event

An event that is raised when a File Upload question starts to download a file. Use this event to implement file preview when your server stores only file names.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionFileModel | QuestionSignaturePadModel
A File Upload or Signature Pad question instance for which the event is raised.
options.name: string
A File Upload question's name.
options.callback: (status: string, data?: any) => any
A callback function that you should call when a file is downloaded successfully or when deletion fails. Pass "success" or "error" as the first argument to indicate the operation status. As the second argument, you can pass the downloaded file's data as a Base64 string if file download was successful or an error message if file download failed.
options.fileValue: any
The File Upload question's value that contains metadata about uploaded files.
options.content: any
A file identifier (URL, file name, etc.) stored in survey results.

View Demo

Type:: EventBase<SurveyModel, DownloadFileEvent>

Implemented in:: SurveyModel

See also:: downloadFile * , onClearFiles * , onUploadFiles

onDragDropAllow event

An event that is raised when users drag and drop survey elements while designing the survey in Survey Creator. Use this event to control drag and drop operations.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.draggedElement: IElement
A survey element being dragged.
options.fromElement: IPanel
A survey element from which draggedElement is being dragged. This parameter is null if draggedElement is being dragged from the Toolbox.
options.toElement: IElement
A survey element to which draggedElement is being dragged.
options.insertBefore: IElement
A survey element before which the target element will be placed. This parameter is null if the parent container (page or panel) has no elements or if the target element will be placed below all other elements within the container.
options.insertAfter: IElement
A survey element after which draggedElement will be placed. This parameter is null if the parent container (page or panel) has no elements or if draggedElement will be placed above all other elements within the container.
options.parent: ISurveyElement
A parent container (page or panel) within which draggedElement will be placed.
options.allow: boolean
A Boolean property that you can set to false if you want to cancel the drag and drop operation.

Type:: EventBase<SurveyModel, DragDropAllowEvent>

Implemented in:: SurveyModel

See also:: isDesignMode

onDynamicPanelAdded event

An event that is raised after a new panel is added to a Dynamic Panel question.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionPanelDynamicModel
A Dynamic Panel question instance for which the event is raised.
options.panel: PanelModel
A Panel instance for which the event is raised.
options.panelIndex: number
The panel's index within Dynamic Panel.

Type:: EventBase<SurveyModel, DynamicPanelModifiedEvent>

Implemented in:: SurveyModel

onDynamicPanelCurrentIndexChanged event

An event that is raised after the current panel is changed in a Dynamic Panel question.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionPanelDynamicModel
A Dynamic Panel question instance for which the event is raised.
options.panel: PanelModel
A panel for which the event is raised.
options.visiblePanelIndex: number
The panel's index in the visiblePanels array of the Dynamic Panel.

Type:: EventBase<SurveyModel, DynamicPanelCurrentIndexChangedEvent>

Implemented in:: SurveyModel

onDynamicPanelItemValueChanged event

An event that is raised after an item value is changed in a panel within a Dynamic Panel question.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionPanelDynamicModel
A Dynamic Panel question instance for which the event is raised.
options.panelData: { [index: string]: any; }
The panel's data object that includes all item values.
options.panelIndex: number
The panel's index within Dynamic Panel.
options.value: any
The item's new value.
options.name: string
The item's name.
options.panel: PanelModel
A panel that nests the item with a changed value.

Type:: EventBase<SurveyModel, DynamicPanelItemValueChangedEvent>

Implemented in:: SurveyModel

onDynamicPanelRemoved event

An event that is raised after a panel is deleted from a Dynamic Panel question.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionPanelDynamicModel
A Dynamic Panel question instance for which the event is raised.
options.panel: PanelModel
A Panel instance for which the event is raised.
options.panelIndex: number
The panel's index within Dynamic Panel.

Type:: EventBase<SurveyModel, DynamicPanelModifiedEvent>

Implemented in:: SurveyModel

onDynamicPanelRemoving event

An event that is raised before a panel is deleted from a Dynamic Panel question. Use this event to cancel the deletion.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionPanelDynamicModel
A Dynamic Panel question instance for which the event is raised.
options.panel: PanelModel
A Panel instance for which the event is raised.
options.panelIndex: number
The panel's index within Dynamic Panel.
options.allow: boolean
A Boolean property that you can set to false if you want to cancel panel deletion.

Type:: EventBase<SurveyModel, DynamicPanelRemovingEvent>

Implemented in:: SurveyModel

onElementContentVisibilityChanged event

An event that is raised after a survey element is expanded or collapsed.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.element: ISurveyElement
A survey element that was expanded or collapsed.

Type:: EventBase<SurveyModel, ElementContentVisibilityChangedEvent>

Implemented in:: SurveyModel

onErrorCustomText event

An event that is raised to change default error messages.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.name: string
A validation error type: "required", "requireoneanswer", "requirenumeric", "exceedsize", "webrequest", "webrequestempty", "otherempty", "uploadingfile", "requiredinallrowserror", "minrowcounterror", "keyduplicationerror", or "custom"
options.obj: Question | PanelModel | SurveyModel
A survey element to which the validation error belongs.
options.error: SurveyError
A validation error.
options.text: string
An error message. You can assign a custom message to this parameter.

Type:: EventBase<SurveyModel, ErrorCustomTextEvent>

Implemented in:: SurveyModel

onFocusInPanel event

An event that is raised when an element within a panel gets focus.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.panel: PanelModel
A Panel instance for which the event is raised.

Type:: EventBase<SurveyModel, FocusInPanelEvent>

Implemented in:: SurveyModel

See also:: onFocusInQuestion * , focusFirstQuestionAutomatic * , focusQuestion

onFocusInQuestion event

An event that is raised when an element (input field, checkbox, radio button) within a question gets focus.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.

Type:: EventBase<SurveyModel, FocusInQuestionEvent>

Implemented in:: SurveyModel

See also:: onFocusInPanel * , focusFirstQuestionAutomatic * , focusQuestion

onGetChoiceDisplayValue event

Use this event to load a display text for the default choice item in Dropdown and Tag Box questions.

If you load choices from a server (use choicesByUrl or onChoicesLazyLoad), display texts become available only when data is loaded, which does not happen until a user opens the drop-down menu. However, a display text for a default choice item is required before that. In this case, you can load data individually for the default item within the onGetChoiceDisplayValue event handler.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.setItems: (displayValues: string[], ...customValues: IValueItemCustomPropValues[]) => void
A method that you should call to assign display texts to the question.
options.values: any[]
An array of one (in Dropdown) or more (in Tag Box) default values.

View Demo

Type:: EventBase<SurveyModel, GetChoiceDisplayValueEvent>

Implemented in:: SurveyModel

onGetDynamicPanelTabTitle event

An event that is raised before a Dynamic Panel renders tab titles. Use this event to change individual tab titles.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionPanelDynamicModel
A Dynamic Panel question instance for which the event is raised.
options.panel: PanelModel
A panel for which the event is raised.
options.visiblePanelIndex: number
The panel's index in the visiblePanels array of the Dynamic Panel.
options.title: string
A tab title. You can change this parameter's value.

View Demo

Type:: EventBase<SurveyModel, DynamicPanelGetTabTitleEvent>

Implemented in:: SurveyModel

onGetExpressionDisplayValue event

An event that is raised before an Expression question displays a value. Use this event to override the display value.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.displayValue: any
A question's display text. You can assign a custom value to this parameter.
options.value: any
An expression value.

Type:: EventBase<SurveyModel, GetExpressionDisplayValueEvent>

Implemented in:: SurveyModel

onGetMatrixRowActions event

An event that allows you to add, delete, or modify actions in rows of a Dynamic Matrix.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.actions: IAction[]
An array of actions. You can modify the entire array or individual actions within it.
options.row: MatrixDropdownRowModelBase
A matrix row for which the event is raised.

View Demo

Type:: EventBase<SurveyModel, GetMatrixRowActionsEvent>

Implemented in:: SurveyModel

See also:: IAction

onGetPageTitleActions event

An event that allows you to add, delete, or modify actions in a page title.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.page: PageModel
A Page instance for which the event is raised.
options.titleActions: IAction[]
An array of actions associated with the processed element.

View Demo

Type:: EventBase<SurveyModel, GetPageTitleActionsEvent>

Implemented in:: SurveyModel

See also:: IAction

onGetPanelFooterActions event

An event that allows you to add, delete, or modify actions in the footer of a Panel.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.actions: IAction[]
An array of actions. You can modify the entire array or individual actions within it.
options.panel: PanelModel
A Panel instance for which the event is raised.
options.question: QuestionPanelDynamicModel
A Dynamic Panel to which the Panel belongs. This field is undefined if the Panel does not belong to any Dynamic Panel.

Type:: EventBase<SurveyModel, GetPanelFooterActionsEvent>

Implemented in:: SurveyModel

See also:: IAction

onGetPanelTitleActions event

An event that allows you to add, delete, or modify actions in a panel title.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.panel: PanelModel
A Panel instance for which the event is raised.
options.titleActions: IAction[]
An array of actions associated with the processed element.

Type:: EventBase<SurveyModel, GetPanelTitleActionsEvent>

Implemented in:: SurveyModel

See also:: IAction

onGetQuestionDisplayValue event

Use this event to change a question's display text.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.displayValue: any
A question's display text. You can assign a custom value to this parameter.

Type:: EventBase<SurveyModel, GetQuestionDisplayValueEvent>

Implemented in:: SurveyModel

onGetQuestionNo event

An event that is raised before the survey calculates a question number. Handle this event to modify question numbers.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.no: string
A question number that is calculated based upon the question's visibleIndex and survey's questionStartIndex properties. You can change this parameter's value.

If you want to hide question numbers, disable the showQuestionNumbers property.

Type:: EventBase<SurveyModel, GetQuestionNoEvent>

Implemented in:: SurveyModel

See also:: onGetQuestionTitle * , questionStartIndex

onGetQuestionTitle event

An event that is raised before the survey displays a question title. Handle this event to modify question titles.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.title: string
A question title taken from the question's title or name property. You can change this parameter's value.

If you want to modify question numbers, handle the onGetQuestionNo event.

Type:: EventBase<SurveyModel, GetQuestionTitleEvent>

Implemented in:: SurveyModel

See also:: requiredText

onGetQuestionTitleActions event

An event that allows you to add, delete, or modify actions in a question title.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.titleActions: IAction[]
An array of actions associated with the processed element.

View Demo

Type:: EventBase<SurveyModel, GetQuestionTitleActionsEvent>

Implemented in:: SurveyModel

See also:: IAction

onGetResult event

An event that is raised when the getResult(resultId, questionName) method is called. Use this event to obtain answers to an individual question from SurveyJS Service.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.response: any
A server response.
options.success: boolean
A Boolean value that indicates whether survey results have been retrieved successfully.
options.data: any
An object with the following structure:

{
  AnswersCount: Number, // A total number of posted answers to the question
  QuestionResult: Object // All unique answers to the question and their number
}

options.dataList: any[]
An array of objects with the following structure:

{
  name: String, // A unique answer to the question
  value: Number // The number of user responses with this answer
}

Type:: EventBase<SurveyModel, GetResultEvent>

Implemented in:: SurveyModel

See also:: getResult

onGetTitleTagName event

An event that is raised when the survey calculates heading levels (<h1>, <h2>, etc.) for a survey, page, panel, and question title. Handle this event to change the heading level of individual titles.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.element: Base
A survey element (question, panel, page, or the survey itself) for which the event is raised.
options.tagName: string
A heading used to render the title ("h1"-"h6"). You can change this parameter's value.

If you want to specify heading levels for all titles, use the titleTags object in global settings.

View Demo

Type:: EventBase<SurveyModel, GetTitleTagNameEvent>

Implemented in:: SurveyModel

See also:: onGetQuestionTitle * , onGetQuestionNo

onIsAnswerCorrect event

An event that is raised to define whether a question answer is correct. Applies only to quiz surveys.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.correctAnswers: number
The number of correct answers in a matrix where each row is considered as one quiz question.
options.incorrectAnswers: number
The number of incorrect answers in a matrix where each row is considered as one quiz question.
options.result: boolean
A Boolean property that specifies whether the answer is correct (true) or incorrect (false). Use the options.question.value and options.question.correctAnswer properties to check the answer.

Type:: EventBase<SurveyModel, IsAnswerCorrectEvent>

Implemented in:: SurveyModel

onItemValuePropertyChanged event

An event that is raised when an ItemValue property is changed.

Parameters:

sender: this
A SurveyJS object whose property contains an array of ItemValue objects.
options.obj: ItemValue
An ItemValue object.
options.propertyName: string
The name of the property to which an array of ItemValue objects is assigned (for example, "choices" or "rows").
options.name: "text" | "value"
The name of the changed property.
options.newValue: any
A new value for the property.

Type:: Event<(sender: Base, options: any) => any, Base, any>

Implemented in:: Base

onLoadChoicesFromServer event

An event that is raised after choices are loaded from a server but before they are assigned to a choice-based question, such as Dropdown or Checkboxes. Handle this event if you need to modify the loaded choices.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.serverResult: any
A query result as it came from the server.
options.choices: ItemValue[]
An array of loaded choices. You can modify this array.

Type:: EventBase<SurveyModel, LoadChoicesFromServerEvent>

Implemented in:: SurveyModel

onLoadedSurveyFromService event

An event that is raised after a survey JSON schema is loaded from the SurveyJS Service. Use this event to modify the loaded schema.

Type:: EventBase<SurveyModel, {}>

Implemented in:: SurveyModel

See also:: surveyId * , clientId * , loadSurveyFromService

onMatrixAfterCellRender event

This event is obsolete. Use the onAfterRenderMatrixCell event instead.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.htmlElement: HTMLElement
A rendered HTML element.
options.cell: MatrixDropdownCell
A matrix cell for which the event is raised.
options.cellQuestion: Question
A Question instance within the matrix cell.
options.row: MatrixDropdownRowModelBase
A matrix row to which the cell belongs.
options.column: MatrixDropdownColumn | MatrixDropdownCell
A matrix column to which the cell belongs.

Type:: EventBase<SurveyModel, MatrixAfterCellRenderEvent>

Implemented in:: SurveyModel

onMatrixAllowRemoveRow event

This event is obsolete. Use the onMatrixRenderRemoveButton event instead.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionMatrixDynamicModel
A Dynamic Matrix question instance for which the event is raised.
options.row: MatrixDropdownRowModelBase
A matrix row for which the event is raised.
options.rowIndex: number
A zero-based row index.
options.allow: boolean
A Boolean property that you can set to false if you want to hide the Remove button for this row.

Type:: EventBase<SurveyModel, MatrixAllowRemoveRowEvent>

Implemented in:: SurveyModel

onMatrixBeforeRowAdded event

This event is obsolete. Use the onMatrixRowAdding event instead.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionMatrixDynamicModel
A Dynamic Matrix question instance for which the event is raised.
options.allow: boolean
A Boolean property that you can set to false if you do not want to add the row.

Type:: EventBase<SurveyModel, MatrixBeforeRowAddedEvent>

Implemented in:: SurveyModel

onMatrixCellCreated event

An event that is raised after a cell in a Multi-Select Matrix or Dynamic Matrix is created.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionMatrixDropdownModelBase
A Multi-Select Matrix question instance for which the event is raised.
options.column: MatrixDropdownColumn
A matrix column to which the cell belongs.
options.columnName: string
The name of the matrix column to which the cell belongs.
options.row: MatrixDropdownRowModelBase
A matrix row to which the cell belongs.
options.rowValue: any
The values of this matrix row.
To access a particular column's value, use the following code: options.rowValue["columnName"]
options.cell: MatrixDropdownCell
A matrix cell for which the event is raised.
options.cellQuestion: Question
A Question instance within the matrix cell. You can use the properties and methods exposed by the instance to customize it.

Type:: EventBase<SurveyModel, MatrixCellCreatedEvent>

Implemented in:: SurveyModel

See also:: onAfterRenderMatrixCell

onMatrixCellCreating event

An event that is raised before a cell in a Multi-Select Matrix or Dynamic Matrix is created. Use this event to change the type of individual matrix cells.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionMatrixDropdownModelBase
A Multi-Select Matrix question instance for which the event is raised.
options.column: MatrixDropdownColumn
A matrix column to which the cell belongs.
options.columnName: string
The name of the matrix column to which the cell belongs.
options.row: MatrixDropdownRowModelBase
A matrix row to which the cell belongs.
options.rowValue: any
The values of this matrix row.
To access a particular column's value, use the following code: options.rowValue["columnName"]
options.cellType: string
The type of this matrix cell. You can change this property value to one of the values described in the cellType documentation.

Type:: EventBase<SurveyModel, MatrixCellCreatingEvent>

Implemented in:: SurveyModel

See also:: onAfterRenderMatrixCell

onMatrixCellValidate event

An event that is raised for Multi-Select Matrix and Dynamic Matrix questions when they validate a cell value. Use this event to display a custom error message based on a condition.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionMatrixDropdownModelBase
A Multi-Select Matrix question instance for which the event is raised.
options.row: MatrixDropdownRowModelBase
A matrix row to which the cell belongs.
options.column: MatrixDropdownColumn
A matrix column to which the cell belongs.
options.columnName: string
The name of a matrix column to which the cell belongs.
options.cellQuestion: Question
A Question instance within the matrix cell. You can use the properties and methods exposed by the instance to customize it.
options.getCellQuestion: (columnName: string) => Question
A method that returns a Question instance within the matrix cell given a column name.
options.value: any
A new cell value.
options.error: string
A field for your custom error message. Default value: undefined.

Type:: EventBase<SurveyModel, MatrixCellValidateEvent>

Implemented in:: SurveyModel

See also:: onMatrixRowAdding

onMatrixCellValueChanged event

An event that is raised after a cell value is changed in a Multi-Select Matrix or Dynamic Matrix.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionMatrixDropdownModelBase
A Multi-Select Matrix question instance for which the event is raised.
options.row: MatrixDropdownRowModelBase
A matrix row to which the cell belongs.
options.column: MatrixDropdownColumn
A matrix column to which the cell belongs.
options.columnName: string
The name of a matrix column to which the cell belongs.
options.cellQuestion: Question
A Question instance within the matrix cell. You can use the properties and methods exposed by the instance to customize it.
options.getCellQuestion: (columnName: string) => Question
A method that returns a Question instance within the matrix cell given a column name.
options.value: any
A new cell value.

Type:: EventBase<SurveyModel, MatrixCellValueChangedEvent>

Implemented in:: SurveyModel

See also:: onMatrixRowAdding

onMatrixCellValueChanging event

An event that is raised before a cell value is changed in a Multi-Select Matrix or Dynamic Matrix. Use this event to change the cell value.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionMatrixDropdownModelBase
A Multi-Select Matrix question instance for which the event is raised.
options.row: MatrixDropdownRowModelBase
A matrix row to which the cell belongs.
options.column: MatrixDropdownColumn
A matrix column to which the cell belongs.
options.columnName: string
The name of a matrix column to which the cell belongs.
options.cellQuestion: Question
A Question instance within the matrix cell. You can use the properties and methods exposed by the instance to customize it.
options.getCellQuestion: (columnName: string) => Question
A method that returns a Question instance within the matrix cell given a column name.
options.value: any
A new cell value.
options.oldValue: any
A previous cell value.

Type:: EventBase<SurveyModel, MatrixCellValueChangingEvent>

Implemented in:: SurveyModel

See also:: onMatrixRowAdding

onMatrixColumnAdded event

An event that is raised after a new column is added to a Multi-Select Matrix or Dynamic Matrix.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.column: any
An added matrix column.

Type:: EventBase<SurveyModel, MatrixColumnAddedEvent>

Implemented in:: SurveyModel

onMatrixDetailPanelVisibleChanged event

An event that is raised after the visibility of an expandable detail section is changed. This event can be raised for Multi-Select and Dynamic Matrix questions.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionMatrixDropdownModelBase
A Multi-Select Matrix question instance for which the event is raised.
options.row: MatrixDropdownRowModelBase
A matrix row to which the detail section belongs.
options.rowIndex: number
A zero-based row index.
options.detailPanel: PanelModel
A PanelModel that represents the detail section.
options.visible: boolean
Indicates whether the detail section is visible now.

Type:: EventBase<SurveyModel, MatrixDetailPanelVisibleChangedEvent>

Implemented in:: SurveyModel

onMatrixRenderRemoveButton event

An event that is raised before rendering the Remove button in a row of a Dynamic Matrix. Use this event to hide the Remove button for individual matrix rows.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionMatrixDynamicModel
A Dynamic Matrix question instance for which the event is raised.
options.row: MatrixDropdownRowModelBase
A matrix row for which the event is raised.
options.rowIndex: number
A zero-based row index.
options.allow: boolean
A Boolean property that you can set to false if you want to hide the Remove button for this row.

Type:: EventBase<SurveyModel, MatrixAllowRemoveRowEvent>

Implemented in:: SurveyModel

See also:: onMatrixRowRemoving * , onMatrixRowRemoved

onMatrixRowAdded event

An event that is raised after a new row is added to a Dynamic Matrix.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionMatrixDynamicModel
A Dynamic Matrix question instance for which the event is raised.
options.row: MatrixDropdownRowModelBase
An added matrix row.

Type:: EventBase<SurveyModel, MatrixRowAddedEvent>

Implemented in:: SurveyModel

onMatrixRowAdding event

An event that is raised before a new row is added to a Dynamic Matrix.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionMatrixDynamicModel
A Dynamic Matrix question instance for which the event is raised.
options.allow: boolean
A Boolean property that you can set to false if you do not want to add the row.

Type:: EventBase<SurveyModel, MatrixBeforeRowAddedEvent>

Implemented in:: SurveyModel

onMatrixRowRemoved event

An event that is raised after a row is deleted from a Dynamic Matrix.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionMatrixDynamicModel
A Dynamic Matrix question instance for which the event is raised.
options.row: MatrixDropdownRowModelBase
A deleted matrix row.
options.rowIndex: number
A zero-based index of the deleted row.

Type:: EventBase<SurveyModel, MatrixRowRemovedEvent>

Implemented in:: SurveyModel

See also:: onMatrixRenderRemoveButton

onMatrixRowRemoving event

An event that is raised before a row is deleted from a Dynamic Matrix. You can cancel row deletion and clear row data instead.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionMatrixDynamicModel
A Dynamic Matrix question instance for which the event is raised.
options.row: MatrixDropdownRowModelBase
A matrix row to be deleted. If you want to clear row data, set the options.row.value property to undefined.
options.rowIndex: number
A zero-based index of the matrix row to be deleted.
options.allow: boolean
A Boolean property that you can set to false if you want to cancel row deletion.

Type:: EventBase<SurveyModel, MatrixRowRemovingEvent>

Implemented in:: SurveyModel

See also:: onMatrixRenderRemoveButton

onMultipleTextItemAdded event

An event that is raised on adding a new item in Multiple Text question.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.item: any
A new added item.

Type:: EventBase<SurveyModel, MultipleTextItemAddedEvent>

Implemented in:: SurveyModel

onNavigateToUrl event

An event that is raised before the survey navigates to a specified URL. Use this event to change the URL or cancel the navigation.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.allow: boolean
A Boolean property that you can set to false if you want to cancel the navigation and show the complete page.
options.url: string
A URL to which respondents should be navigated. You can modify this parameter's value.

Type:: EventBase<SurveyModel, NavigateToUrlEvent>

Implemented in:: SurveyModel

See also:: navigateToUrl * , navigateToUrlOnCondition

onOpenFileChooser event

An event that is raised when Survey Creator opens a dialog window for users to select files.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.input: HTMLInputElement
A file input HTML element.
options.element: Base
A survey element (question, panel, page, or survey) or a theme JSON schema for which this event is raised.
options.elementType: String
The type of the element passed as the options.element parameter.
Possible values: "theme", "header", or any value returned from the getType() method.
options.propertyName: String
The name of the survey element property or theme property for which files are being selected.
options.item: ItemValue
A choice item for which the event is raised. This parameter has a value only when the dialog window is opened to select images for an Image Picker question.
options.callback: (files: any[]) => void
A callback function to which you should pass selected files.

Type:: EventBase<SurveyModel, OpenFileChooserEvent>

Implemented in:: SurveyModel

See also:: onUploadFile * , uploadFiles

onPageAdded event

An event that is raised when a new page is added to the survey.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.page: PageModel
A Page instance for which the event is raised.

Type:: EventBase<SurveyModel, PageAddedEvent>

Implemented in:: SurveyModel

See also:: PanelModel

onPageVisibleChanged event

An event that is raised after page visibility is changed.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.visible: boolean
Indicates whether the element is visible now.
options.page: PageModel
A Page instance for which the event is raised.

Refer to the following help topic for information on how to implement conditional visibility: Conditional Visibility.

Type:: EventBase<SurveyModel, PageVisibleChangedEvent>

Implemented in:: SurveyModel

onPanelAdded event

An event that is raised when a new panel is added to a page.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.panel: PanelModel
A Panel instance for which the event is raised.
options.page: PanelModelBase
A page that nests the added element.
options.parent: PanelModelBase
The parent container (panel or page).
options.index: number
The element's index within the parent container (panel or page).
options.name: string
The question's name.

Type:: EventBase<SurveyModel, PanelAddedEvent>

Implemented in:: SurveyModel

onPanelRemoved event

An event that is raised after a panel is deleted from the survey.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.panel: PanelModel
A Panel instance for which the event is raised.
options.name: string
The element's name.

Type:: EventBase<SurveyModel, PanelRemovedEvent>

Implemented in:: SurveyModel

onPanelVisibleChanged event

An event that is raised after panel visibility is changed.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.visible: boolean
Indicates whether the element is visible now.
options.panel: PanelModel
A Panel instance for which the event is raised.

Refer to the following help topic for information on how to implement conditional visibility: Conditional Visibility.

Type:: EventBase<SurveyModel, PanelVisibleChangedEvent>

Implemented in:: SurveyModel

onPartialSend event

An event that is raised to save incomplete survey results. Enable the sendResultOnPageNext property for this event to occur.

For information on event handler parameters, refer to descriptions within the interface.

Alternatively, you can handle the onCurrentPageChanged and onValueChanged events, as shown in the following demo: Continue an Incomplete Survey.

Type:: EventBase<SurveyModel, {}>

Implemented in:: SurveyModel

onPopupVisibleChanged event

An event that is raised after the visibility of a popup is changed. This event can be raised for Single- and Multi-Select Dropdown questions and Rating questions rendered as drop-down menus.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.popup: PopupModel<any>
An object that describes the popup.
options.visible: boolean
Indicates whether the popup is visible now.

Type:: EventBase<SurveyModel, PopupVisibleChangedEvent>

Implemented in:: SurveyModel

onProcessHtml event

An event that is raised when the survey processes HTML content. Handle this event to modify HTML content before displaying.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.html: string
HTML markup. You can modify this parameter's value.
options.reason: string
Indicates a page, question, or message for which HTML content is intended: "completed" | "completed-before" | "loading" | "html-question".

Type:: EventBase<SurveyModel, ProcessHtmlEvent>

Implemented in:: SurveyModel

See also:: completedHtml * , loadingHtml * , QuestionHtmlModel.html

onProcessTextValue event

An event that is raised when the survey processes dynamic texts and any text in curly brackets. Use this event, for instance, to substitute parameters in a RESTful URL with real values when you load choices by URL.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.name: string
The name of the value being processed (the text in curly brackets).
options.value: any
The value being processed. You can change this parameter's value.

Type:: EventBase<SurveyModel, ProcessTextValueEvent>

Implemented in:: SurveyModel

onProgressText event

An event that is raised before the survey displays progress text. Handle this event to change the progress text in code.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.questionCount: number
The number of questions with input fields. Image, HTML, and Expression questions are not counted.
options.answeredQuestionCount: number
The number of answered questions.
options.requiredQuestionCount: number
The number of questions marked as required.
options.requiredAnsweredQuestionCount: number
The number of answered questions marked as required.
options.text: string
Progress text rendered in the progress bar. You can change this parameter's value.

Type:: EventBase<SurveyModel, ProgressTextEvent>

Implemented in:: SurveyModel

See also:: showProgressBar * , progressBarType

onPropertyChanged event

An event that is raised when a property of this SurveyJS object has changed.

Parameters:

sender: this
A SurveyJS object whose property has changed.
options.name: string
The name of the changed property.
options.newValue: any
A new value for the property.
options.oldValue: any
An old value of the property. If the property is an array, oldValue contains the same array as newValue does.

Type:: EventBase<Base, any>

Implemented in:: Base

onQuestionAdded event

An event that is raised when a new question is added to a panel or page.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.page: PanelModelBase
A page that nests the added element.
options.parent: PanelModelBase
The parent container (panel or page).
options.index: number
The element's index within the parent container (panel or page).
options.name: string
The question's name.

To use this event for questions loaded from JSON, create an empty survey model, add an event handler, and only then populate the model from the JSON object:

import { Model } from "survey-core";

const surveyJson = {
   // ...
};
// Create an empty model
const survey = new Model();
// Add an event handler
survey.onQuestionAdded.add((sender, options) => {
  //...
});
// Load the survey JSON schema
survey.fromJSON(surveyJson);

Type:: EventBase<SurveyModel, QuestionAddedEvent>

Implemented in:: SurveyModel

See also:: onQuestionCreated

onQuestionCreated event

An event that is raised when the survey creates any new object derived from Question.

In a survey, complex elements (Dynamic Matrix, Multiple Text, and Dynamic Panel) are composed of questions. Use this event to customize any question regardless of which survey element it belongs to.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.

To use this event for questions loaded from JSON, create an empty survey model, add an event handler, and only then populate the model from the JSON object:

import { Model } from "survey-core";

const surveyJson = {
   // ...
};
// Create an empty model
const survey = new Model();
// Add an event handler
survey.onQuestionCreated.add((sender, options) => {
  //...
});
// Load the survey JSON schema
survey.fromJSON(surveyJson);

Type:: EventBase<SurveyModel, QuestionCreatedEvent>

Implemented in:: SurveyModel

See also:: onQuestionAdded

onQuestionRemoved event

An event that is raised after a question is deleted from the survey.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.name: string
The element's name.

Type:: EventBase<SurveyModel, QuestionRemovedEvent>

Implemented in:: SurveyModel

onQuestionVisibleChanged event

An event that is raised after question visibility is changed.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.visible: boolean
Indicates whether the element is visible now.
options.name: string
The question's name.

Refer to the following help topic for information on how to implement conditional visibility: Conditional Visibility.

Type:: EventBase<SurveyModel, QuestionVisibleChangedEvent>

Implemented in:: SurveyModel

onScrollingElementToTop event

An event this is raised before a survey element (usually page) is scrolled to the top. Use this event to cancel the scroll operation.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.element: ISurveyElement
A survey element that will be scrolled to the top.
options.elementId: string
A unique element ID within the DOM.
options.cancel: boolean
A Boolean property that you can set to true if you want to cancel the scroll operation.

Type:: EventBase<SurveyModel, ScrollingElementToTopEvent>

Implemented in:: SurveyModel

onSendResult event

An event that is raised after a request to save survey results on SurveyJS Service has been completed. Use this event to find out if the results have been saved successfully.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.response: any
A server response.
options.success: boolean
A Boolean value that indicates whether survey results have been saved successfully.

Type:: EventBase<SurveyModel, SendResultEvent>

Implemented in:: SurveyModel

onServerValidateQuestions event

Use this event to validate data on your server.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.complete: () => void
A method that you should call when a request to the server has completed.
options.errors: { [index: string]: any; }
An object for your error messages. Set error messages as follows: options.errors["questionName"] = "My error message".
options.data: { [index: string]: any; }
Question values. You can get an individual question value as follows: options.data["questionName"].

View Demo

Type:: EventBase<SurveyModel, ServerValidateQuestionsEvent>

Implemented in:: SurveyModel

See also:: onValidateQuestion * , onValidatePanel * , isValidatingOnServer

onSettingQuestionErrors event

An event that is raised before errors are assigned to a question. Use this event to add/remove/modify errors.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.errors: SurveyError[]
An array of errors. The array is empty if the validated question satisfies all validation rules.

Type:: EventBase<SurveyModel, SettingQuestionErrorsEvent>

Implemented in:: SurveyModel

See also:: onValidateQuestion

onShowingChoiceItem event

An event that is raised before a choice item is displayed. Use this event to change the visibility of individual choice items in Checkboxes, Dropdown, Radio Button Group, and other similar question types.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.item: ItemValue
A choice item.
options.visible: boolean
A Boolean value that specifies item visibility. Set it to false to hide the item.

Type:: EventBase<SurveyModel, ShowingChoiceItemEvent>

Implemented in:: SurveyModel

onShowingPreview event

An event that is raised before the survey displays a preview of given answers. Use this event to cancel the preview.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.allow: boolean
A Boolean property that you can set to false if you want to cancel the preview.

Type:: EventBase<SurveyModel, ShowingPreviewEvent>

Implemented in:: SurveyModel

See also:: showPreviewBeforeComplete * , showPreview * , cancelPreview

onStarted event

An event that is raised when the survey state changes to "running".

Type:: EventBase<SurveyModel, {}>

Implemented in:: SurveyModel

See also:: firstPageIsStarted

onTextMarkdown event

An event that is raised to convert Markdown content to HTML.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.name: string
The name of the property that contains the text to process.
options.element: Question | PanelModel | PageModel | SurveyModel
A survey element (question, panel, page, or survey) in which the text will be rendered.
options.text: string
A string with Markdown content. Convert this content to HTML and assign the result to the options.html parameter.
options.html: string
A property to which you should assign HTML content.

View Demo

Type:: EventBase<SurveyModel, TextMarkdownEvent>

Implemented in:: SurveyModel

onTextRenderAs event

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.name: string
The name of the property that contains the text to process.
options.element: Question | PanelModel | PageModel | SurveyModel
A survey element (question, panel, page, or survey) in which the text will be rendered.
options.renderAs: string
a component name used for text rendering

Type:: EventBase<SurveyModel, TextRenderAsEvent>

Implemented in:: SurveyModel

onTimer event

An event that is raised every second while the timer is running.

Use the timeSpent property to find out how many seconds have elapsed.

Type:: EventBase<SurveyModel, {}>

Implemented in:: SurveyModel

See also:: maxTimeToFinish * , maxTimeToFinishPage * , showTimerPanel * , startTimer

onTimerPanelInfoText event

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.text: string
the timer panel info text

Type:: EventBase<SurveyModel, TimerPanelInfoTextEvent>

Implemented in:: SurveyModel

onTriggerExecuted event

An event that is raised after a trigger is executed.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.trigger: Trigger
A trigger that has been executed.

Conditional Survey Logic (Triggers).

Type:: EventBase<SurveyModel, TriggerExecutedEvent>

Implemented in:: SurveyModel

See also:: triggers * , runTriggers

onUpdateChoiceItemCss event

An event that is raised before rendering a choice item in Radio Button Group, Checkboxes, and Dropdown questions. Use it to override default CSS classes applied to choice items.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.item: ItemValue
A choice item. To access its value and display text, use the options.item.value and options.item.text properties.
options.css: string
A string with CSS classes applied to the choice item. The CSS classes are separated by a space character. You can modify this string to apply custom CSS classes.

View Demo

Type:: EventBase<SurveyModel, UpdateChoiceItemCssEvent>

Implemented in:: SurveyModel

See also:: css

onUpdatePageCssClasses event

An event that is raised before rendering a page. Use it to override default page CSS classes.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.page: PageModel
A Page instance for which the event is raised.
options.cssClasses: any
An object with CSS classes applied to the element being rendered, for example, { root: "class1", button: "class2" }. You can modify this object to apply custom CSS classes.

View Demo

Type:: EventBase<SurveyModel, UpdatePageCssClassesEvent>

Implemented in:: SurveyModel

See also:: css

onUpdatePanelCssClasses event

An event that is raised before rendering a standalone panel and panels within Dynamic Panel. Use it to override default panel CSS classes.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.panel: PanelModel
A Panel instance for which the event is raised.
options.cssClasses: any
An object with CSS classes applied to the element being rendered, for example, { root: "class1", button: "class2" }. You can modify this object to apply custom CSS classes.

View Demo

Type:: EventBase<SurveyModel, UpdatePanelCssClassesEvent>

Implemented in:: SurveyModel

See also:: css

onUpdateQuestionCssClasses event

An event that is raised before rendering a question. Use it to override default question CSS classes.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.cssClasses: any
An object with CSS classes applied to the element being rendered, for example, { root: "class1", button: "class2" }. You can modify this object to apply custom CSS classes.

View Demo

Type:: EventBase<SurveyModel, UpdateQuestionCssClassesEvent>

Implemented in:: SurveyModel

See also:: css

onUploadFiles event

An event that is raised when a File Upload or Signature Pad question starts to upload a file. Applies only if storeDataAsText is false. Use this event to upload files to your server.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: QuestionFileModel | QuestionSignaturePadModel
A File Upload or Signature Pad question instance for which the event is raised.
options.name: string
A File Upload question's name.
options.callback: (data: any, errors?: any) => any
A callback function that you should call when a file is uploaded successfully or when file upload fails. Pass an array of successfully uploaded files as the first argument. As the second argument, you can pass an array of error messages if file upload failed.
options.files: any[]
An array of JavaScript File objects that represent files to upload.

View Demo

Type:: EventBase<SurveyModel, UploadFilesEvent>

Implemented in:: SurveyModel

See also:: uploadFiles * , onDownloadFile * , onClearFiles

onValidatedErrorsOnCurrentPage event

An event that is raised when the current page is being validated. Handle this event to be notified of current page validation.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.page: PageModel
A Page instance for which the event is raised.
options.questions: Question[]
An array of questions with validation errors.
options.errors: SurveyError[]
An array of validation errors.

Type:: EventBase<SurveyModel, ValidatedErrorsOnCurrentPageEvent>

Implemented in:: SurveyModel

onValidatePanel event

An event that is raised when a panel is being validated. Use this event to specify a custom error message.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.panel: PanelModel
A Panel instance for which the event is raised.
options.error: string
An error message that you should specify if validation fails.
options.name: string
The panel's name.

View Demo

Type:: EventBase<SurveyModel, ValidatePanelEvent>

Implemented in:: SurveyModel

See also:: onValidateQuestion * , onServerValidateQuestions

onValidateQuestion event

An event that is raised when a question value is being validated. Use this event to specify a custom error message.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.error: string
An error message that you should specify if validation fails.
options.value: any
A question value being validated.
options.name: string
The question's name.

View Demo

Type:: EventBase<SurveyModel, ValidateQuestionEvent>

Implemented in:: SurveyModel

See also:: onServerValidateQuestions * , onValidatePanel * , onMatrixCellValidate * , onSettingQuestionErrors

onValueChanged event

An event that is raised after a question value is changed.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.name: string
The name of the question whose value is being changed. If you use the valueName property, this parameter contains its value.
options.value: any
A new value.

To handle value changes in matrix cells or panels within a Dynamic Panel, use the onMatrixCellValueChanged or onDynamicPanelItemValueChanged event.

Type:: EventBase<SurveyModel, ValueChangedEvent>

Implemented in:: SurveyModel

See also:: setValue

onValueChanging event

An event that is raised before a question value is changed.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.question: Question
A Question instance for which the event is raised.
options.name: string
The name of the question whose value is being changed. If you use the valueName property, this parameter contains its value.
options.value: any
A new value. You can change it if required.
options.oldValue: any
A previous value.

Type:: EventBase<SurveyModel, ValueChangingEvent>

Implemented in:: SurveyModel

See also:: setValue

onVariableChanged event

An event that is raised after a variable or calculated value is changed.

Parameters:

sender: SurveyModel
A survey instance that raised the event.
options.value: any
A new value for the variable or calculated value.
options.name: string
The name of the variable or calculated value that has been changed.

Type:: EventBase<SurveyModel, VariableChangedEvent>

Implemented in:: SurveyModel

See also:: setVariable * , calculatedValues

pageCount property

Returns a total number of survey pages.

To get the number of visible pages, use the visiblePageCount property.

Type:: number readonly

Implemented in:: SurveyModel

See also:: pages

pageNextText property

Gets or sets a caption for the Next button.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: Localization & Globalization

pagePrevText property

Gets or sets a caption for the Previous button.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: Localization & Globalization

pages property

Returns an array of all pages in the survey.

To get an array of only visible pages, use the visiblePages array.

Type:: PageModel[] readonly

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: PageModel

previewText property

Gets or sets a caption for the Preview button.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: showPreviewBeforeComplete * , showPreview * , editText

prevPage method

Switches the survey to the previous page.

This method returns a Boolean value that indicates whether the page was successfully switched. false is returned if the current page is the first page.

Type:: () => boolean

Return Value:: true if the page was successfully switched; false otherwise.

Implemented in:: SurveyModel

See also:: isFirstPage * , nextPage

processedCompletedBeforeHtml property

Returns HTML content displayed to a user who has completed the survey before. To identify such users, the survey uses a cookie name or client ID.

To specify HTML content, use the completedBeforeHtml property.

Type:: string readonly

Implemented in:: SurveyModel

processedCompletedHtml property

Returns HTML content displayed on the complete page.

To specify HTML content, use the completedHtml property.

Type:: string readonly

Implemented in:: SurveyModel

processedLoadingHtml property

Returns HTML content displayed while a survey JSON schema is being loaded from SurveyJS Service.

To specify HTML content, use the loadingHtml property.

Type:: string readonly

Implemented in:: SurveyModel

progressBarInheritWidthFrom property

Specifies whether the progress bar spans the width of the survey or that of the survey container. Applies only when the progress bar is visible and progressBarType is "pages".

Possible values:

"survey"
The progress bar width is the same as the survey width.
"container" (default)
The progress bar width is the same as the survey container width.

Type:: "survey" | "container" readonly

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: container

Accepted values:: container , survey

Implemented in:: SurveyModel

See also:: progressBarShowPageTitles * , progressBarShowPageNumbers

progressBarShowPageNumbers property

Specifies whether the progress bar displays page numbers. Applies only when the progress bar is visible and progressBarType is "pages".

Default value: false

Type:: boolean readonly

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: progressBarShowPageTitles * , progressBarInheritWidthFrom

progressBarShowPageTitles property

Specifies whether the progress bar displays page titles. Applies only when the progress bar is visible and progressBarType is "pages".

Default value: false

Type:: boolean readonly

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: progressBarShowPageNumbers * , progressBarInheritWidthFrom

progressBarType property

Specifies the type of information displayed by the progress bar. Applies only when showProgressBar is not "off".

Possible values:

"pages" (default) - The number of completed pages.
"questions" - The number of answered questions.
"requiredQuestions" - The number of answered required questions.
"correctQuestions" - The number of correct questions in a quiz.
"buttons" - (Obsolete) Use the "pages" property value with the progressBarShowPageTitles property set to true instead.

When progressBarType is set to "pages", you can also enable the progressBarShowPageNumbers and progressBarShowPageTitles properties if you want to display page numbers and titles in the progress bar.

View Demo

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: pages

Accepted values:: pages , questions , requiredQuestions , correctQuestions

Implemented in:: SurveyModel

See also:: progressValue

progressText property

Returns text displayed by the progress bar (for instance, "Page 2 of 3" or "Answered 3/8 questions"). Handle the onProgressText event to change this text.

Type:: string readonly

Implemented in:: SurveyModel

See also:: progressValue * , showProgressBar * , progressBarType

progressValue property

Returns a percentage value that indicates user progress in the survey.

Type:: number readonly

Implemented in:: SurveyModel

See also:: showProgressBar * , progressBarType * , progressText

questionDescriptionLocation property

Specifies where to display question descriptions.

Possible values:

"underTitle" (default) - Displays descriptions under question titles.
"underInput" - Displays descriptions under the interactive area.

You can override this setting for individual questions if you specify their descriptionLocation property.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: underTitle

Accepted values:: underInput , underTitle

Implemented in:: SurveyModel

questionErrorLocation property

Specifies the error message position.

Possible values:

"top" (default) - Displays error messages above questions.
"bottom" - Displays error messages below questions.

You can override this setting if you specify the questionErrorLocation property for an individual page or panel or set the errorLocation property for a specific question.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: top

Accepted values:: top , bottom

Implemented in:: SurveyModel

questionsOnPageMode property

Specifies how to distribute survey elements between pages.

Possible values:

"singlePage" - Combines all survey pages into a single page.
"questionPerPage" - Creates a separate page for every question.
"standard" (default) - Retains the original structure specified in the JSON schema.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: standard

Accepted values:: standard , singlePage , questionPerPage

Implemented in:: SurveyModel

questionsOrder property

Specifies the sort order of questions in the survey.

Possible values:

"initial" (default) - Preserves the original order of questions.
"random" - Displays questions in random order.

You can override this property for individual pages and panels.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: initial

Accepted values:: initial , random

Implemented in:: SurveyModel

See also:: PageModel.questionsOrder * , PanelModel.questionsOrder

questionStartIndex property

Specifies the initial number or letter from which to start question numbering.

Question Numbers

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

questionTitleLocation property

Gets or sets question title location relative to the input field: "top", "bottom", or "left".

Certain question types (Matrix, Multiple Text) do not support the "left" value. For them, the "top" value is used.

You can override this setting if you specify the questionTitleLocation property for an individual page or panel or set the titleLocation property for a specific question.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: top

Accepted values:: top , bottom , left

Implemented in:: SurveyModel

questionTitlePattern property

Specifies a pattern for question titles.

Refer to the following help topic for more information: Title Pattern.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: numTitleRequire

Implemented in:: SurveyModel

registerPropertyChangedHandlers method

Registers a function to call when a property value changes.

Type:: (propertyNames: string[], handler: any, key?: string) => void

Parameters:: propertyNames, type: string[] ,
An array of one or multiple property names.

handler, type: any ,
A function to call when one of the listed properties change.

key, type: string ,
(Optional) A key that identifies the current registration. If a function for one of the properties is already registered with the same key, the function will be overwritten. You can also use the key to subsequently unregister handlers.

Implemented in:: Base

See also:: unregisterPropertyChangedHandlers

removePage method

Removes a page from the survey.

Pass a PageModel object to this method. You can get this object in different ways. For example, you can call the getPageByName() method to obtain a PageModel object with a specific name or use the currentPage property to access and delete the current page, as shown in the code below.

// Delete the current page
survey.removePage(survey.currentPage);

Type:: (page: PageModel) => void

Parameters:: page, type: PageModel ,
A page to remove.

Implemented in:: SurveyModel

See also:: addNewPage

requiredText property

Specifies one or multiple characters that designate required questions.

Default value: *

View Demo

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: *

Implemented in:: SurveyModel

runCondition method

Calculates a given expression and returns true or false.

Type:: (expression: string) => boolean

Parameters:: expression, type: string ,
An expression to calculate.

Implemented in:: SurveyModel

runExpression method

Calculates a given expression and returns a result value.

Type:: (expression: string) => any

Parameters:: expression, type: string ,
An expression to calculate.

Implemented in:: SurveyModel

runExpressions method

Recalculates all expressions in the survey.

Type:: () => void

Implemented in:: SurveyModel

runTriggers method

Executes all triggers, except "complete".

Conditional Survey Logic (Triggers)

Type:: () => void

Implemented in:: SurveyModel

See also:: onTriggerExecuted

sendResult method

Posts a survey result to SurveyJS Service.

Type:: (postId?: string, clientId?: string, isPartial?: boolean) => void

Parameters:: postId, type: string ,
An identifier used to save survey results. You can find it on the My Surveys page. If you do not specify this parameter, the survey uses the surveyPostId property value.

clientId, type: string ,
A respondent identifier (e-mail or other unique ID). This ID ensures that the respondent does not pass the same survey twice.

isPartial, type: boolean ,
Pass true to save partial survey results (see Continue an Incomplete Survey).

Implemented in:: SurveyModel

sendResultOnPageNext property

Specifies whether to save survey results when respondents switch between pages. Handle the onPartialSend event to implement the save operation.

Alternatively, you can handle the onCurrentPageChanged and onValueChanged events, as shown in the following demo: Continue an Incomplete Survey.

Type:: boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

setComment method

Sets a comment value to a question with a specified name.

Type:: (name: string, newValue: string, locNotification?: any) => void

Parameters:: name, type: string ,
A question name.

newValue, type: string ,
A new comment value.

locNotification, type: any ,
For internal use.

Implemented in:: SurveyModel

See also:: getComment

setCookie method

Sets a cookie with a specified cookieName in the browser. If the cookieName property value is defined, this method is automatically called on survey completion.

Type:: () => void

Implemented in:: SurveyModel

See also:: hasCookie * , deleteCookie

setPropertyValue method

Assigns a new value to a specified property.

Type:: (name: string, val: any) => void

Parameters:: name, type: string ,
A property name.

val, type: any ,
A new value for the property.

Implemented in:: Base

setValue method

Sets a question value (answer).

This method executes all triggers and reevaluates conditions (visibleIf, requiredId, and others). It also switches the survey to the next page if the goNextPageAutomatic property is enabled and all questions on the current page have correct answers.

Type:: (name: string, newQuestionValue: any, locNotification?: any, allowNotifyValueChanged?: boolean, questionName?: string) => void

Parameters:: name, type: string ,
A question name.

newQuestionValue, type: any

locNotification, type: any ,
For internal use.

allowNotifyValueChanged, type: boolean ,
For internal use.

questionName, type: string

Implemented in:: SurveyModel

See also:: data * , getValue

setVariable method

Sets a variable value.

Variables help topic

Type:: (name: string, newValue: any) => void

Parameters:: name, type: string ,
A variable name.

newValue, type: any ,
A new variable value.

Implemented in:: SurveyModel

See also:: getVariable * , getVariableNames

showCompleteButton property

Specifies whether to display the Complete button. Set this property to false if respondents should not complete the survey.

Type:: boolean writable

Implemented in:: SurveyModel

See also:: showNavigationButtons * , showPrevButton

showCompletedPage property

Specifies whether to show the complete page.

Type:: boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: True

Implemented in:: SurveyModel

See also:: onComplete * , navigateToUrl

showInvisibleElements property

Specifies whether to show all survey elements, regardless of their visibility.

Default value: false

Type:: boolean writable

Implemented in:: SurveyModel

showNavigationButtons property

Gets or sets the position of the Start, Next, Previous, and Complete navigation buttons and controls their visibility.

Possible values:

"bottom" (default) - Displays the navigation buttons below survey content.
"top" - Displays the navigation buttons above survey content.
"both" - Displays the navigation buttons above and below survey content.
"none" - Hides the navigation buttons. This setting may be useful if you implement custom external navigation.

Type:: any writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: bottom

Accepted values:: none , top , bottom , both

Implemented in:: SurveyModel

See also:: goNextPageAutomatic * , showPrevButton * , showCompleteButton

showPageNumbers property

Specifies whether page titles contain page numbers.

View Demo

Type:: boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

showPageTitles property

Specifies whether to display page titles.

Type:: boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: True

Implemented in:: SurveyModel

showPrevButton property

Specifies whether to display the Previous button. Set this property to false if respondents should not move backward along the survey.

Type:: boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: True

Implemented in:: SurveyModel

See also:: showNavigationButtons * , showCompleteButton

showPreview method

Displays a preview of given answers. Returns false if the preview cannot be displayed because of validation errors.

Type:: () => boolean

Implemented in:: SurveyModel

See also:: cancelPreview * , showPreviewBeforeComplete * , onShowingPreview * , state

showPreviewBeforeComplete property

Allows respondents to preview answers before they are submitted.

Possible values:

"showAllQuestions" - Displays all questions in the preview.
"showAnsweredQuestions" - Displays only answered questions in the preview.
"noPreview" (default) - Hides the preview.

View Demo

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: noPreview

Accepted values:: noPreview , showAllQuestions , showAnsweredQuestions

Implemented in:: SurveyModel

See also:: showPreview * , cancelPreview

showProgressBar property

Controls the visibility of the progress bar and specifies its position.

Possible values:

"off" (default) - Hides the progress bar.
"aboveHeader" - Displays the progress bar above the survey header.
"belowHeader" - Displays the progress bar below the survey header.
"bottom" - Displays the progress bar below survey content.
"topBottom" - Displays the progress bar above and below survey content.
"auto" - Displays the progress bar below the survey header if the header has a background image or color. Otherwise, the progress bar is displayed above the header.
"top" - (Obsolete) Use the "aboveHeader" or "belowHeader" property value instead.
"both" - (Obsolete) Use the "topBottom" property value instead.

View Demo

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: off

Accepted values:: off , auto , aboveHeader , belowHeader , bottom , topBottom

Implemented in:: SurveyModel

See also:: progressBarType * , progressValue

showQuestionNumbers property

Specifies whether to display question numbers and how to calculate them.

Possible values:

true or "on" - Displays question numbers.
"onpage" - Displays question numbers and starts numbering on each page from scratch.
false or "off" - Hides question numbers.

View Demo

If you want to hide the number of an individual question, enable its hideNumber property.

Type:: string | boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: on

Accepted values:: on , onPage , off

Implemented in:: SurveyModel

showTimerPanel property

Displays the timer panel and specifies its position. Applies only to quiz surveys.

Possible values:

"top" - Displays the timer panel at the top of the survey.
"bottom" - Displays the timer panel at the bottom of the survey.
"none" (default) - Hides the timer panel.

If the timer panel is displayed, the timer starts automatically when the survey begins. To specify time limits, use the maxTimeToFinish and maxTimeToFinishPage properties.

The timer panel displays information about time spent on an individual page and the entire survey. If you want to display only the page timer or the survey timer, set the showTimerPanelMode property to "page" or "survey".

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: none

Accepted values:: none , top , bottom

Implemented in:: SurveyModel

See also:: startTimer * , stopTimer * , timeSpent * , onTimer

showTimerPanelMode property

Specifies whether the timer panel displays timers for the current page, the entire survey, or both. Applies only if the timer panel is visible.

Possible values:

"survey" - Displays only the survey timer.
"page" - Displays only the page timer.
"all" (default) - Displays both the survey and page timers.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: all

Accepted values:: page , survey , all

Implemented in:: SurveyModel

See also:: timeSpent * , onTimer * , startTimer * , stopTimer

showTitle property

Specifies whether to display the survey title.

View Demo

Type:: boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: True

Implemented in:: SurveyModel

See also:: title

showTOC property

Gets or sets the visibility of the table of contents.

Default value: false

View Demo

Type:: boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: tocLocation

start method

Starts the survey. Applies only if the survey has a start page.

Type:: () => boolean

Implemented in:: SurveyModel

See also:: firstPageIsStarted * , completeLastPage

startedPage property

Returns the start page. Applies only if the firstPageIsStarted property is set to true.

Refer to the following help topic for more information: Start Page.

Type:: PageModel readonly

Implemented in:: SurveyModel

See also:: firstPageIsStarted * , activePage

startSurveyText property

Gets or sets a caption for the Start button.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: firstPageIsStarted * , Localization & Globalization

startTimer method

Starts a timer that calculates how many seconds a respondent has spent on the survey. Applies only to quiz surveys.

Type:: () => void

Implemented in:: SurveyModel

See also:: stopTimer * , maxTimeToFinish * , maxTimeToFinishPage * , timeSpent * , onTimer

state property

Returns the current survey state.

Possible values:

"loading" - The survey is being loaded from a JSON schema.
"empty" - The survey has no elements to display.
"starting" - The survey displays a start page.
"running" - A respondent is taking the survey.
"preview" - A respondent is previewing answers before submitting them.
"completed" - A respondent has completed the survey and submitted the results.

Type:: string readonly

Implemented in:: SurveyModel

stopTimer method

Stops the timer. Applies only to quiz surveys.

Type:: () => void

Implemented in:: SurveyModel

See also:: startTimer * , maxTimeToFinish * , maxTimeToFinishPage * , timeSpent * , onTimer

storeOthersAsComment property

Specifies whether to store the "Other" option response in a separate property.

Default value: true

Respondents can leave comments when they select "Other" in choice-based questions, such as Dropdown or Checkboxes. Comment values are saved in a separate property. The property name is composed of the question name and commentSuffix. However, you can use the question name as a key to store the comment value instead. Disable the storeOthersAsComment property in this case.

Type:: boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: True

Implemented in:: SurveyModel

See also:: maxOthersLength

surveyId property

The identifier of a survey JSON schema to load from SurveyJS Service.

Refer to the following help topic for more information: Store Survey Results in the SurveyJS Service.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: loadSurveyFromService * , onLoadedSurveyFromService

surveyPostId property

An identifier used to save survey results to SurveyJS Service.

Refer to the following help topic for more information: Store Survey Results in the SurveyJS Service.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: onComplete * , surveyShowDataSaving

surveyShowDataSaving property

Specifies whether to show progress when the survey sends data to SurveyJS Service.

View Demo

Type:: boolean writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: surveyPostId

textUpdateMode property

Specifies when to update the question value in questions with a text input field.

Possible values:

"onBlur" (default) - Updates the value after the input field loses focus.
"onTyping" - Updates the value on every key press.

Do not use the "onTyping" mode if your survey contains many expressions. Expressions are reevaluated each time a question value is changed. In "onTyping" mode, the question value changes frequently. This may cause performance degradation.

You can override this setting for individual questions: textUpdateMode.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: onBlur

Accepted values:: onBlur , onTyping

Implemented in:: SurveyModel

timeSpent property

A time period that a respondent has spent on the survey so far; measured in seconds. Applies only to quiz surveys.

Assign a number to this property if you need to start the quiz timer from a specific time (for instance, if you want to continue an interrupted quiz).

You can also find out how many seconds a respondent has spent on an individual survey page. To do this, use the timeSpent property of a PageModel object.

Type:: number writable

Implemented in:: SurveyModel

See also:: maxTimeToFinish * , maxTimeToFinishPage * , startTimer

title property

A title for the survey element. If title is undefined, the name property value is displayed instead.

Empty pages and panels do not display their titles or names.

Type:: string writable

Implemented in:: SurveyElementCore

See also:: Configure Question Titles

tocLocation property

Gets or sets the position of the table of contents. Applies only when the table of contents is visible.

Possible values:

"left" (default)
"right"

View Demo

Type:: "left" | "right" writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: left

Accepted values:: left , right

Implemented in:: SurveyModel

See also:: showTOC

toJSON method

Returns a JSON object that corresponds to the current SurveyJS object.

Type:: (options?: ISaveToJSONOptions) => any

Parameters:: options, type: ISaveToJSONOptions

Implemented in:: Base

See also:: fromJSON

triggers property

A list of triggers in the survey.

Conditional Survey Logic (Triggers)

Type:: SurveyTrigger[] writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

See also:: runTriggers * , onTriggerExecuted

unregisterPropertyChangedHandlers method

Unregisters value change event handlers for the specified properties.

Type:: (propertyNames: string[], key?: string) => void

Parameters:: propertyNames, type: string[] ,
An array of one or multiple property names.

key, type: string ,
(Optional) A key of the registration that you want to cancel.

Implemented in:: Base

See also:: registerPropertyChangedHandlers

uploadFiles method

Uploads files to a server.

The following code shows how to call this method:

const question = survey.getQuestionByName("myFileQuestion");
survey.uploadFiles(
  question,
  question.name,
  question.value,
  (data, errors) => {
    // ...
  }
);

Type:: (question: QuestionFileModel | QuestionSignaturePadModel, name: string, files: any[], callback: (data: any, errors?: any) => any) => void

Parameters:: question, type: QuestionFileModel | QuestionSignaturePadModel ,
A File Upload question instance or Signature Pad question instance.

name, type: string ,
The File Upload question's name or Signature Pad question's name.

files, type: any[] ,
An array of JavaScript File objects that represent files to upload.

callback, type: (data: any, errors?: any) => any ,
A callback function that allows you to access successfully uploaded files as the first argument. If any files fail to upload, the second argument contains an array of error messages.

Implemented in:: SurveyModel

See also:: onUploadFiles * , downloadFile

validate method

Validates all questions and returns false if the validation fails.

If you use validation expressions and at least one of them calls an async function, the validate method returns undefined. In this case, you should pass a callback function as the onAsyncValidation parameter. The function's hasErrors Boolean parameter will contain the validation result.

Type:: (fireCallback?: boolean, focusOnFirstError?: boolean, onAsyncValidation?: (hasErrors: boolean) => void) => boolean

Parameters:: fireCallback, type: boolean ,
(Optional) Pass false if you do not want to show validation errors in the UI.

focusOnFirstError, type: boolean ,
(Optional) Pass true if you want to focus the first question with a validation error. The survey will be switched to the page that contains this question if required.

onAsyncValidation, type: (hasErrors: boolean) => void ,
(Optional) Pass a callback function. It accepts a Boolean hasErrors parameter that equals true if the validation fails or false otherwise.

Implemented in:: SurveyModel

See also:: validateCurrentPage * , validatePage

validateCurrentPage method

Validates all questions on the current page and returns false if the validation fails.

If you use validation expressions and at least one of them calls an async function, the validateCurrentPage method returns undefined. In this case, you should pass a callback function as the onAsyncValidation parameter. The function's hasErrors Boolean parameter will contain the validation result.

Type:: (onAsyncValidation?: (hasErrors: boolean) => void) => boolean

Parameters:: onAsyncValidation, type: (hasErrors: boolean) => void ,
(Optional) Pass a callback function. It accepts a Boolean hasErrors parameter that equals true if the validation fails or false otherwise.

Implemented in:: SurveyModel

See also:: currentPage * , validate * , validateCurrentPage

validatePage method

Validates all questions on a specified page and returns false if the validation fails.

If you use validation expressions and at least one of them calls an async function, the validatePage method returns undefined. In this case, you should pass a callback function as the onAsyncValidation parameter. The function's hasErrors Boolean parameter will contain the validation result.

Type:: (page?: PageModel, onAsyncValidation?: (hasErrors: boolean) => void) => boolean

Parameters:: page, type: PageModel ,
Pass the PageModel that you want to validate. You can pass undefined to validate the activePage.

onAsyncValidation, type: (hasErrors: boolean) => void ,
(Optional) Pass a callback function. It accepts a Boolean hasErrors parameter that equals true if the validation fails or false otherwise.

Implemented in:: SurveyModel

See also:: validate * , validateCurrentPage

validationAllowComplete property

Specifies whether respondents can end a survey with validation errors.

Default value: false

Type:: boolean readonly

Implemented in:: SurveyModel

See also:: checkErrorsMode

validationAllowSwitchPages property

Specifies whether respondents can switch the current page even if it contains validation errors.

Default value: false

Type:: boolean readonly

Implemented in:: SurveyModel

See also:: checkErrorsMode

validationEnabled property

Specifies whether data validation is enabled.

Default value: true

Type:: boolean readonly

Implemented in:: SurveyModel

See also:: checkErrorsMode * , hideRequiredErrors

visiblePageCount property

Returns the number of visible survey pages.

To get a total number of survey pages, use the pageCount property.

Type:: number readonly

Implemented in:: SurveyModel

See also:: visiblePages * , Conditional Visibility

visiblePages property

Returns an array of visible pages without the start page.

To get an array of all pages, use the pages property. If all pages are visible, the pages and visiblePages arrays are identical.

Type:: PageModel[] readonly

Implemented in:: SurveyModel

See also:: Conditional Visibility

width property

A survey width in CSS values.

Default value: undefined (the survey inherits the width from its container)

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Implemented in:: SurveyModel

widthMode property

Specifies how to calculate the survey width.

Possible values:

"static" - A survey has a fixed width.
"responsive" - A survey occupies all available horizontal space and stretches or shrinks horizontally to fit in the screen size.
"auto" (default) - Survey width depends on a question type and corresponds to the "static" or "responsive" mode.

Type:: string writable

This property is stored in the survey JSON definition and can be edited in the Survey Creator.

Default value:: auto

Accepted values:: auto , static , responsive

Implemented in:: SurveyModel

SurveyModel

Properties

Methods

Events

Your cookie settings

Your renewal subscription expires soon.

Your renewal subscription has expired.

Your cookie settings

Privacy Overview

Your renewal subscription expires soon.

Your renewal subscription has expired.