SurveyModel
The SurveyModel
object contains properties and methods that allow you to control the survey and access its elements.
Inherited from the following class(es):
Properties
Methods
Events
Returns startedPage
if the survey currently displays a start page; otherwise, returns currentPage
.
- Type:
- any readonly
- Implemented in:
- SurveyModel
- See also:
- startedPage * , currentPage * , firstPageIsStarted
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"
|"navigationbuttons"
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 tocomponent
.
- 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
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
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
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
- Implemented in:
- SurveyModel
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
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
An image to display in the background of the survey or form. Accepts a base64 or URL string value.
- 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:
- backgroundOpacity
A value from 0 to 1 that specifies how transparent the survey background should be: 0 makes the background 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
- See also:
- backgroundImage
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
Cancels a preview of given answers and switches the survey to the page specified by the curPage
parameter.
- Type:
- (curPage?: any) => void
- Parameters:
-
curPage, 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
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 , onValueChanging , onComplete
- Implemented in:
- SurveyModel
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
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
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
Removes a value from the survey results.
- Type:
- (name: string) => void
- Parameters:
-
name, type: string ,
The name of the value. Typically it is a question name.
- Implemented in:
- SurveyModel
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
A user identifier (e-mail or other unique ID).
If your application works with the 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
Creates a new object that has the same type and properties as the current SurveyJS object.
- Type:
- () => Base
- Implemented in:
- Base
An object with all comment values.
- Type:
- any readonly
- Implemented in:
- SurveyModel
- See also:
- Question.showCommentArea * , storeOthersAsComment
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 a comment when they select "Other" in a single- or multi-select question, 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.
- Type:
- string writable
- Implemented in:
- SurveyModel
HTML content displayed to a user who has completed the survey before.
- 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 * , cookieName * , processedCompletedBeforeHtml
HTML content displayed on the complete 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:
- showCompletedPage * , completedHtmlOnCondition
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.
- Type:
- HtmlConditionItem[] writable
This property is stored in the survey JSON definition and can be edited in the Survey Creator.
- Implemented in:
- SurveyModel
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
Gets or sets the 'Complete' button caption.
- 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:
- locale
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:
- cliendId
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
Gets or sets an object in which keys are UI elements and values are CSS classes applied to them.
- Type:
- any writable
- Implemented in:
- SurveyModel
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
A zero-based index of the current page in the visiblePages
array.
- Type:
- number writable
- Implemented in:
- SurveyModel
- See also:
- visiblePages
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
Deletes the cookie with cookieName
from the browser.
- Type:
- () => void
- Implemented in:
- SurveyModel
- See also:
- cookieName * , hasCookie * , setCookie
Explanatory text displayed under the title.
- Type:
- string writable
- Implemented in:
- SurveyElementCore
- See also:
- hasDescription
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
ornavigateToUrlOnCondition
property. - Calls the
sendResult()
method if Form Library works with the 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) => boolean
- Parameters:
-
isCompleteOnTrigger, type: boolean ,
For internal use.
- Return Value:
- `false` if survey completion is cancelled within the [`onCompleting`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onCompleting) event handler; otherwise, `true`.
- Implemented in:
- SurveyModel
- See also:
- surveyPostId
Downloads a file from server
- Type:
- (question: QuestionFileModel, questionName: string, fileValue: any, callback: (status: string, data: any) => any) => void
- Parameters:
-
question, type: QuestionFileModelquestionName, type: stringfileValue, type: any ,
a single file question value
callback, type: (status: string, data: any) => any ,a call back function to get the status on downloading the file and the downloaded file content
- Implemented in:
- SurveyModel
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
Returns the text displayed when a survey has no visible pages and questions.
- Type:
- string readonly
- Implemented in:
- SurveyModel
Checks whether survey elements (pages, panels, and questions) have unique question names. You can check for unique names for individual page and panel (and all their elements) or a question. If the parameter is not specified, then a survey checks that all its elements have unique names.
- Type:
- (element?: ISurveyElement) => void
- Parameters:
-
element, type: ISurveyElement ,
page, panel or question, it is
null
by default, that means all survey elements will be checked
- Implemented in:
- SurveyModel
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
Focuses the first question on the current page.
- Type:
- () => void
- Implemented in:
- SurveyModel
- See also:
- focusQuestion * , focusFirstQuestionAutomatic
Specifies whether to focus the first question on the page on survey startup or when users switch between pages.
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:
- focusOnFirstError * , focusFirstQuestion * , focusQuestion
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
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
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) => void
- Parameters:
-
json, type: any ,
A JSON object with properties that you want to apply to the current SurveyJS object.
- Implemented in:
- Base
- See also:
- toJSON
Returns a list of all survey's panels.
- Type:
- (visibleOnly?: boolean, includingDesignTime?: boolean) => IPanel[]
- Parameters:
-
visibleOnly, type: booleanincludingDesignTime, type: boolean
- Implemented in:
- SurveyModel
Returns a list of all questions in a survey.
- Type:
- (visibleOnly?: boolean, includingDesignTime?: boolean) => Question[]
- Parameters:
-
visibleOnly, type: boolean ,
set it
true
, if you want to get only visible questionsincludingDesignTime, type: boolean
- Implemented in:
- SurveyModel
Returns the comment value.
- Type:
- (name: string) => string
- Parameters:
-
name, type: string ,
A comment's name.
- Implemented in:
- SurveyModel
- See also:
- setComment
Returns a page on which an element (question or panel) is placed.
- Type:
- (element: IElement) => PageModel
- Parameters:
-
element, type: IElement ,
Question or Panel
- Implemented in:
- SurveyModel
Returns a page by it's name.
- Type:
- (name: string) => PageModel
- Parameters:
-
name, type: string
- Implemented in:
- SurveyModel
Returns a page on which a question is located.
- Type:
- (question: IQuestion) => PageModel
- Parameters:
-
question, type: IQuestion
- Implemented in:
- SurveyModel
Returns a list of pages by their names.
- Type:
- (names: string[]) => PageModel[]
- Parameters:
-
names, type: string[] ,
a list of page names
- Implemented in:
- SurveyModel
Returns a panel by its name.
- Type:
- (name: string, caseInsensitive?: boolean) => PanelModel
- Parameters:
-
name, type: string ,
a panel name
caseInsensitive, type: boolean
- Implemented in:
- SurveyModel
- See also:
- getQuestionByName
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?: { includeEmpty?: boolean; includeQuestionTypes?: boolean; includeValues?: boolean; calculations?: { propertyName: string; }[]; }) => IQuestionPlainData[]
- Parameters:
-
options, type: { includeEmpty?: boolean; includeQuestionTypes?: boolean; includeValues?: boolean; calculations?: { propertyName: string; }[]; }
- Implemented in:
- SurveyModel
Returns the progress that a user made while going through the survey. It depends from progressBarType property
- Type:
- () => number
- Implemented in:
- SurveyModel
- See also:
- progressBarType * , progressValue
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
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
Returns a question by its name.
- Type:
- (name: string, caseInsensitive?: boolean) => Question
- Parameters:
-
name, type: string ,
a question name
caseInsensitive, type: boolean
- Implemented in:
- SurveyModel
- See also:
- getQuestionByValueName
Returns a question by its value name
- Type:
- (valueName: string, caseInsensitive?: boolean) => IQuestion
- Parameters:
-
valueName, type: string ,
a question name
caseInsensitive, type: boolean
- Implemented in:
- SurveyModel
- See also:
- getQuestionByName * , getQuestionsByValueName * , Question.valueName
Gets a list of questions by their names.
- Type:
- (names: string[], caseInsensitive?: boolean) => IQuestion[]
- Parameters:
-
names, type: string[] ,
an array of question names
caseInsensitive, type: boolean
- Implemented in:
- SurveyModel
Returns all questions by their valueName. name property is used if valueName property is empty.
- Type:
- (valueName: string, caseInsensitive?: boolean) => Question[]
- Parameters:
-
valueName, type: string ,
a question name
caseInsensitive, type: boolean
- Implemented in:
- SurveyModel
- See also:
- getQuestionByName * , getQuestionByValueName * , Question.valueName
Returns quiz question number. It may be different from getQuizQuestions.length
because some widgets like matrix may have several questions.
- Type:
- () => number
- Implemented in:
- SurveyModel
- See also:
- getQuizQuestions
Returns quiz questions. All visible questions that has input(s) widgets.
- Type:
- () => IQuestion[]
- Implemented in:
- SurveyModel
- See also:
- getQuizQuestionCount
Calls the api.surveyjs.io service and, on callback, fires the onGetResult
event with all answers that your users made for a question.
- Type:
- (resultId: string, name: string) => void
- Parameters:
-
name, type: string ,
The question name
- Implemented in:
- SurveyModel
- See also:
- onGetResult
Returns an array of locales that are used in the survey's translation.
- Type:
- () => string[]
- Implemented in:
- SurveyModel
Returns a question value (answer) by a question's name.
- Type:
- (name: string) => any
- Parameters:
-
name, type: string ,
A question name
- Implemented in:
- SurveyModel
Returns a variable value. Variable, unlike values, are not stored in the survey results.
- Type:
- (name: string) => any
- Parameters:
-
name, type: string ,
A variable name
- Implemented in:
- SurveyModel
- See also:
- SetVariable
Returns all variables in the survey. Use setVariable function to create a new variable.
- Type:
- () => string[]
- Implemented in:
- SurveyModel
- See also:
- getVariable * , setVariable
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: Checkbox, Boolean (rendered as Checkbox), Comment, Signature Pad, Image Picker (with Multi Select), File, Single-Choice Matrix (not all rows are answered), Dynamic Matrix, Panel Dynamic.
- Type:
- boolean | "autogonext" writable
This property is stored in the survey JSON definition and can be edited in the Survey Creator.
- Implemented in:
- SurveyModel
Returns true
, if a user has already completed the survey in this browser and there is a cookie about it. Survey goes to completedbefore
state if the function returns true
.
- Type:
- boolean readonly
- Implemented in:
- SurveyModel
- See also:
- cookieName * , setCookie * , deleteCookie * , state
Returns true
if the survey element has a description.
- Type:
- boolean readonly
- Implemented in:
- SurveyElementCore
- See also:
- description
Gets or sets whether to hide all required errors.
- Type:
- boolean readonly
- Implemented in:
- SurveyModel
Gets or sets whether the survey must ignore validation like required questions and others, on nextPage
and completeLastPage
function calls. The default is false
.
- Type:
- boolean readonly
- Implemented in:
- SurveyModel
- See also:
- nextPage * , completeLastPage * , mode
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
Returns true
if the current page does not contain errors.
- Type:
- boolean readonly
- Implemented in:
- SurveyModel
- See also:
- currentPage
Returns true
if the survey is in design mode. It is used by SurveyJS Editor.
- Type:
- boolean readonly
- Implemented in:
- SurveyModel
- See also:
- setDesignMode
Returns true
if the survey is in display mode or in preview mode.
- Type:
- boolean readonly
- Implemented in:
- SurveyModel
- See also:
- mode * , showPreviewBeforeComplete
Returns true
if the survey is in edit mode.
- Type:
- boolean readonly
- Implemented in:
- SurveyModel
- See also:
- mode
Returns true
if the survey contains no pages. The survey is empty.
- Type:
- boolean readonly
- Implemented in:
- SurveyModel
Returns true
if the object configuration is being loaded from JSON.
- Type:
- boolean readonly
- Implemented in:
- Base
Survey is showing a page right now. It is in "running", "preview" or starting state.
- Type:
- boolean readonly
- Implemented in:
- SurveyModel
The started page is showing right now. survey state equals to "starting"
- Type:
- boolean readonly
- Implemented in:
- SurveyModel
Gets whether the question values on the current page are validating on the server at the current moment.
- Type:
- boolean readonly
- Implemented in:
- SurveyModel
- See also:
- onServerValidateQuestions
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. Passfalse
to disable this functionality.
- Implemented in:
- Base
The list of errors on loading survey JSON. If the list is empty after loading a JSON, then the JSON is correct and has no errors.
- Type:
- JsonError[] readonly
- Implemented in:
- SurveyModel
- See also:
- JsonError
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
By default all rows are rendered no matters if they are visible or not. Set it true, and survey markup rows will be rendered only if they are visible in viewport. This feature is experimantal and might do not support all the use cases.
- Type:
- boolean writable
- Implemented in:
- SurveyModel
HTML content displayed while a survey JSON schema is being loaded from 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:
- surveyId * , processedLoadingHtml
Loads the survey JSON from the api.surveyjs.io service.
If clientId
is not null
and a user had completed a survey before, the survey switches to completedbefore
state.
- Type:
- (surveyId?: string, cliendId?: string) => void
- Parameters:
-
cliendId, type: string
- Implemented in:
- SurveyModel
- See also:
- state * , onLoadedSurveyFromService
Gets or sets the survey locale. The default value it is empty, this means the 'en' locale is used. You can set it to 'de' - German, 'fr' - French and so on. The library has built-in localization for several languages. The library has a multi-language support as well.
- Type:
- string writable
This property is stored in the survey JSON definition and can be edited in the Survey Creator.
- Accepted values:
- , id , ca , cy , da , de , et , es , eu , fr , hi , hr , it , kk , lv , lt , hu , ms , nl , no , pl , pt , pt-br , ro , sk , rs , fi , sv , sw , tel , tr , vi , nl-BE , is , cs , gr , bg , mk , ru , tg , ua , he , ar , fa , th , ka , ja , zh-cn , zh-tw , ko
- Implemented in:
- SurveyModel
Gets or sets a survey logo.
- 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:
- title
The logo fit mode.
- 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
Gets or sets a survey logo height.
- 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:
- logo
Gets or sets a survey logo position.
- 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
Gets or sets a survey logo width.
- 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:
- logo
Gets or sets the default maximum length for question comments and others
The default value is 0
, that means that the question comments have the same max length as the standard HTML input - 524288 characters: https://www.w3schools.com/tags/att_input_maxlength.asp.
- 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:
- Question.showCommentArea * , Question.showOtherItem * , maxTextLength
Specifies the default maximum length for questions like text and comment, including matrix cell questions.
The default value is 0
, that means that the text and comment have the same max length as the standard HTML input - 524288 characters: https://www.w3schools.com/tags/att_input_maxlength.asp.
- 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
Gets or sets the maximum time in seconds that end user has to complete a survey. If the value is 0 or less, an end user has no time limit to finish a survey.
- 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:
- startTimer * , maxTimeToFinishPage
Gets or sets the maximum time in seconds that end user has to complete a page in the survey. If the value is 0 or less, an end user has no time limit.
You may override this value for every page.
- 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:
- startTimer * , maxTimeToFinish * , PageModel.maxTimeToFinish
Merges a specified data object with the object from the data
property.
Refer to the following help topic for more information: Merge 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
Gets or sets the survey edit mode.
The following options are available:
edit
(default) - make a survey editable,display
- make a survey read-only.
- 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
Navigates user to the next page.
Returns false
in the following cases:
- if the current page is the last page.
- if the current page contains errors (for example, a required question is empty).
- Type:
- () => boolean
- Implemented in:
- SurveyModel
- See also:
- isCurrentPageValid * , prevPage * , completeLastPage
An event that is raised right after a page is rendered in DOM. Use it to modify HTML elements.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.htmlElement
:HTMLElement
The rendered HTML element.
- Type:
- EventBase<SurveyModel, AfterRenderHeaderEvent>
- Implemented in:
- SurveyModel
An event that is raised right after a page is rendered in DOM. Use it to modify HTML elements.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.htmlElement
:HTMLElement
The rendered HTML element.options.page
:PageModel
A Page instance for which the event is raised.
- Type:
- EventBase<SurveyModel, AfterRenderPageEvent>
- Implemented in:
- SurveyModel
An event that is raised right after a panel is rendered in DOM. Use it to modify HTML elements.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.htmlElement
:HTMLElement
The rendered HTML element.options.panel
:PanelModel
A Panel instance for which the event is raised.
- Type:
- EventBase<SurveyModel, AfterRenderPanelEvent>
- Implemented in:
- SurveyModel
An event that is raised right after a question is rendered in DOM. Use it to modify HTML elements.
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
The rendered HTML element.
- Type:
- EventBase<SurveyModel, AfterRenderQuestionEvent>
- Implemented in:
- SurveyModel
An event that is raised right after a non-composite question (text, comment, dropdown, radiogroup, checkbox) is rendered in DOM. Use it to modify HTML elements. This event is not fired for matrices, panels, multiple text and image picker.
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
The rendered HTML element.
- Type:
- EventBase<SurveyModel, AfterRenderQuestionInputEvent>
- Implemented in:
- SurveyModel
An event that is raised right after survey is rendered in DOM.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.htmlElement
:HTMLElement
The rendered HTML element.options.survey
:SurveyModel
- Type:
- EventBase<SurveyModel, AfterRenderSurveyEvent>
- Implemented in:
- SurveyModel
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 thechoices
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'schoicesLazyLoadPageSize
property to change this number.options.skip
:number
The number of choice items to skip.
- Type:
- EventBase<SurveyModel, ChoicesLazyLoadEvent>
- Implemented in:
- SurveyModel
This event is fired on clearing the value in a QuestionFile. Use this event to remove files stored on your server.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.question
:QuestionFileModel
A File question instance for which the event is raised.options.name
:string
the question nameoptions.callback
:(status: string, data?: any) => any
a callback function to get the operation statusoptions.fileName
:string
a removed file's name, set it tonull
to clear all filesoptions.value
:any
the question value
- Type:
- EventBase<SurveyModel, ClearFilesEvent>
- Implemented in:
- SurveyModel
- See also:
- onDownloadFile * , onUploadFiles
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
Returnstrue
if survey completion is caused by the "complete" trigger.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 thetext
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 thetext
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 thetext
parameter to display a custom message.options.showDataSaving
:(text?: string) => void
options.showDataSavingError
:(text?: string) => void
options.showDataSavingSuccess
:(text?: string) => void
options.showDataSavingClear
:(text?: string) => void
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 theoptions.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
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
Returnstrue
if survey completion is caused by the "complete" trigger.options.allow
:boolean
Set this property tofalse
if you want to prevent survey completion.options.allowComplete
:boolean
- Type:
- EventBase<SurveyModel, CompletingEvent>
- Implemented in:
- SurveyModel
- See also:
- onComplete * , doComplete * , allowCompleteSurveyAutomatic
An event that is raised after the current page is switched.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.isPrevPage
:boolean
Returnstrue
if the respondent is switching to the previous page.options.isNextPage
:boolean
Returnstrue
if the respondent is switching to the next page.options.isGoingBackward
:boolean
Returnstrue
if the respondent is going backward, that is,newCurrentPage
is earlier in the survey thanoldCurrentPage
.options.isGoingForward
:boolean
Returnstrue
if the respondent is going forward along the survey.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
An event that is raised before the current page is switched.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.isPrevPage
:boolean
Returnstrue
if the respondent is switching to the previous page.options.isNextPage
:boolean
Returnstrue
if the respondent is switching to the next page.options.isGoingBackward
:boolean
Returnstrue
if the respondent is going backward, that is,newCurrentPage
is earlier in the survey thanoldCurrentPage
.options.isGoingForward
:boolean
Returnstrue
if the respondent is going forward along the survey.options.newCurrentPage
:PageModel
The current page.options.oldCurrentPage
:PageModel
A page that used to be current.options.allow
:boolean
Set this property tofalse
if you do not want to switch the current page.options.allowChanging
:boolean
- Type:
- EventBase<SurveyModel, CurrentPageChangingEvent>
- Implemented in:
- SurveyModel
- See also:
- currentPageNo * , nextPage * , prevPage **
An event that is raised on downloading a file in QuestionFile. Use this event to pass the file to a preview.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.question
:QuestionFileModel
A File question instance for which the event is raised.options.name
:string
the question nameoptions.callback
:(status: string, data?: any) => any
a callback function to get the file downloading status and the downloaded file contentoptions.fileValue
:any
single file question valueoptions.content
:any
the file content
- Type:
- EventBase<SurveyModel, DownloadFileEvent>
- Implemented in:
- SurveyModel
- See also:
- downloadFile * , onClearFiles * , onUploadFiles
Use this event to control drag&drop operations during design mode.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.insertAfter
:IElement
an element after the target element is dragging. It can benull
if parent container (page or panel) is empty or dragging element to the first position within the parent containeroptions.insertBefore
:IElement
an element before the target element is dragging. It can benull
if parent container (page or panel) is empty or dragging an element after the last element in a containeroptions.parent
:ISurveyElement
a page or panel where target element is draggingoptions.source
:IElement
a source element. It can benull
, if it is a new element, dragging from toolboxoptions.target
:IElement
a target element that is draggedoptions.allow
:boolean
set it tofalse
to disable dragging
- Type:
- EventBase<SurveyModel, DragDropAllowEvent>
- Implemented in:
- SurveyModel
- See also:
- setDesignMode * , isDesignMode
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
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
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
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
Set this property tofalse
if you want to cancel the panel deletion.
- Type:
- EventBase<SurveyModel, DynamicPanelRemovingEvent>
- Implemented in:
- SurveyModel
An event that is raised after the survey element content was collapsed or expanded.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.element
:ISurveyElement
Specifies which survey element content was collapsed or expanded
- Type:
- EventBase<SurveyModel, ElementContentVisibilityChangedEvent>
- Implemented in:
- SurveyModel
- See also:
- onElementContentVisibilityChanged
Use the event to change the default error text.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.name
:string
the error name. The following error names are available: required, requireoneanswer, requirenumeric, exceedsize, webrequest, webrequestempty, otherempty, uploadingfile, requiredinallrowserror, minrowcounterror, keyduplicationerror, customoptions.obj
:Question | PanelModel | SurveyModel
an instance of Question, Panel or Survey object to where error is locatedoptions.error
:SurveyError
an instance of theSurveyError
objectoptions.text
:string
an error text
- Type:
- EventBase<SurveyModel, ErrorCustomTextEvent>
- Implemented in:
- SurveyModel
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
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
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[]) => 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.
- Type:
- EventBase<SurveyModel, GetChoiceDisplayValueEvent>
- Implemented in:
- SurveyModel
An event that is raised before expression question convert it's value into display value for rendering.
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
The question value
- Type:
- EventBase<SurveyModel, GetExpressionDisplayValueEvent>
- Implemented in:
- SurveyModel
Use this event to create/customize actions to be displayed in a matrix question's row.
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
:any
A matrix row for which the event is fired
- Type:
- EventBase<SurveyModel, GetMatrixRowActionsEvent>
- Implemented in:
- SurveyModel
- See also:
- IAction * , QuestionMatrixDropdownModelBase
Use this event to create/customize actions to be displayed in a page's 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.
- Type:
- EventBase<SurveyModel, GetPageTitleActionsEvent>
- Implemented in:
- SurveyModel
Use this event to create/customize actions to be displayed in a panel's 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 * , PanelModel
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
Use this event to change the question no in code. If you want to remove question numbering then set showQuestionNumbers to "off".
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 calculated question no, based on questionvisibleIndex
, survey.questionStartIndex
properties. You can change it
- Type:
- EventBase<SurveyModel, GetQuestionNoEvent>
- Implemented in:
- SurveyModel
- See also:
- showQuestionNumbers * , questionStartIndex
Use this event to change the question title in code. If you want to remove question numbering then set showQuestionNumbers to "off".
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 calculated question title, based on questiontitle
,name
- Type:
- EventBase<SurveyModel, GetQuestionTitleEvent>
- Implemented in:
- SurveyModel
- See also:
- showQuestionNumbers * , requiredText
Show More
Use this event to create/customize actions to be displayed in a question's 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.
- Type:
- EventBase<SurveyModel, GetQuestionTitleActionsEvent>
- Implemented in:
- SurveyModel
Use it to get results after calling the getResult
method. It returns a simple analytics from api.surveyjs.io service.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.response
:any
the server responseoptions.dataList
:any[]
an array of objects{name, value}
, wherename
is a unique value/answer to the question andvalue
is a number/count of such answersoptions.data
:any
the object{AnswersCount, QuestionResult : {} }
.AnswersCount
is the number of posted survey results.QuestionResult
is an object with all possible unique answers to the question and number of these answersoptions.success
:boolean
it istrue
if the results were got from the service successfully
- Type:
- EventBase<SurveyModel, GetResultEvent>
- Implemented in:
- SurveyModel
- See also:
- getResult
Use this event to change the element title tag name that renders by default.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.tagName
:string
an element title tagName that are used to render a title. You can change it from the default valueoptions.element
:Base
an element (question, panel, page and survey) that SurveyJS is going to render
- Type:
- EventBase<SurveyModel, GetTitleTagNameEvent>
- Implemented in:
- SurveyModel
- See also:
- showQuestionNumbers * , requiredText
Use this event to define, whether an answer to a question is correct or not.
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
you may change the default number of correct or incorrect answers in the question, for example for matrix, where each row is a quiz questionoptions.incorrectAnswers
:number
options.result
:boolean
returnstrue
, if an answer is correct, orfalse
, if the answer is not correct. Use questions'value
andcorrectAnswer
properties to return the correct value
- Type:
- EventBase<SurveyModel, IsAnswerCorrectEvent>
- Implemented in:
- SurveyModel
- See also:
- Question.value * , Question.correctAnswer
An event that is raised when an ItemValue
property is changed.
Parameters:
sender
:this
A SurveyJS object whose property contains an array ofItemValue
objects.options.obj
:ItemValue
AnItemValue
object.options.propertyName
:String
The name of the property to which an array ofItemValue
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
An event that is raised after choices for radiogroup, checkbox, and dropdown has been loaded from a RESTful service and before they are assigned to a question. You may change the choices, before they are assigned or disable/enabled make visible/invisible question, based on loaded results.
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 result that comes from the server as it isoptions.choices
:ItemValue[]
the loaded choices. You can change the loaded choices to before they are assigned to question
- Type:
- EventBase<SurveyModel, LoadChoicesFromServerEvent>
- Implemented in:
- SurveyModel
An event that is raised after survey is loaded from api.surveyjs.io service. You can use this event to perform manipulation with the survey model after it was loaded from the web service.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.
- Type:
- EventBase<SurveyModel, {}>
- Implemented in:
- SurveyModel
- See also:
- surveyId * , loadSurveyFromService
Parameters:
sender
:SurveyModel
A survey instance that raised the event.
- Type:
- EventBase<SurveyModel, {}>
- Implemented in:
- SurveyModel
An event that is raised for every cell after is has been rendered in 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
The rendered HTML element.options.row
:MatrixDropdownRowModelBase
the matrix row objectoptions.column
:MatrixDropdownColumn | MatrixDropdownCell
the matrix column objectoptions.cellQuestion
:Question
the question/editor in the celloptions.cell
:MatrixDropdownCell
the matrix cell
- Type:
- EventBase<SurveyModel, MatrixAfterCellRenderEvent>
- Implemented in:
- SurveyModel
An event that is raised before rendering "Remove" button for removing a row from Matrix Dynamic question.
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. Set it tofalse
to disable the row removingoptions.row
:any
a row objectoptions.rowIndex
:number
a row index
- Type:
- EventBase<SurveyModel, MatrixAllowRemoveRowEvent>
- Implemented in:
- SurveyModel
An event that is raised before adding a new row in Matrix Dynamic question.
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.canAddRow
:boolean
specifies whether a new row can be added
- Type:
- EventBase<SurveyModel, MatrixBeforeRowAddedEvent>
- Implemented in:
- SurveyModel
An event that is raised for every cell created in Matrix Dynamic and Matrix Dropdown questions.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.question
:QuestionMatrixDropdownModelBase
A Multiple-Choice Matrix question instance for which the event is raised.options.row
:MatrixDropdownRowModelBase
the matrix row objectoptions.columnName
:string
the matrix column nameoptions.column
:MatrixDropdownColumn
the matrix column objectoptions.rowValue
:any
the value of the current row. To access a particular column's value within the current row, use:options.rowValue["columnValue"]
options.cellQuestion
:Question
the question/editor in the cell. You may customize it, change it's properties, like choices or visibleoptions.cell
:MatrixDropdownCell
the matrix cell
- Type:
- EventBase<SurveyModel, MatrixCellCreatedEvent>
- Implemented in:
- SurveyModel
An event that is raised before creating cell question in the matrix. You can change the cell question type by setting different options.cellType.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.question
:QuestionMatrixDropdownModelBase
A Multiple-Choice Matrix question instance for which the event is raised.options.row
:MatrixDropdownRowModelBase
the matrix row objectoptions.columnName
:string
the matrix column nameoptions.column
:MatrixDropdownColumn
the matrix column objectoptions.rowValue
:any
the value of the current row. To access a particular column's value within the current row, use:options.rowValue["columnValue"]
options.cellType
:string
the cell question type. You can change it
- Type:
- EventBase<SurveyModel, MatrixCellCreatingEvent>
- Implemented in:
- SurveyModel
An event that is raised when Matrix Dynamic and Matrix Dropdown questions validate the cell value.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.question
:QuestionMatrixDropdownModelBase
A Multiple-Choice Matrix question instance for which the event is raised.options.getCellQuestion
:(columnName: string) => Question
the function that returns the cell question by column nameoptions.row
:MatrixDropdownRowModelBase
the matrix row objectoptions.value
:any
a new valueoptions.columnName
:string
the matrix column nameoptions.error
:string
an error string. It is empty by default
- Type:
- EventBase<SurveyModel, MatrixCellValidateEvent>
- Implemented in:
- SurveyModel
An event that is raised when cell value is changed in Matrix Dynamic and Matrix Dropdown questions.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.question
:QuestionMatrixDropdownModelBase
A Multiple-Choice Matrix question instance for which the event is raised.options.getCellQuestion
:(columnName: string) => Question
the function that returns the cell question by column nameoptions.row
:MatrixDropdownRowModelBase
the matrix row objectoptions.value
:any
a new valueoptions.columnName
:string
the matrix column name
- Type:
- EventBase<SurveyModel, MatrixCellValueChangedEvent>
- Implemented in:
- SurveyModel
An event that is raised on changing cell value in Matrix Dynamic and Matrix Dropdown questions. You may change the options.value
property to change a cell value.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.question
:QuestionMatrixDropdownModelBase
A Multiple-Choice Matrix question instance for which the event is raised.options.getCellQuestion
:(columnName: string) => Question
the function that returns the cell question by column nameoptions.row
:MatrixDropdownRowModelBase
the matrix row objectoptions.value
:any
a new valueoptions.columnName
:string
the matrix column nameoptions.oldValue
:any
the old value
- Type:
- EventBase<SurveyModel, MatrixCellValueChangingEvent>
- Implemented in:
- SurveyModel
An event that is raised on adding a new column in Matrix Dynamic or Matrix Dropdown question.
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
A new added column.
- Type:
- EventBase<SurveyModel, MatrixColumnAddedEvent>
- Implemented in:
- SurveyModel
An event that is raised on adding a new row in Matrix Dynamic question.
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
:any
a new added row
- Type:
- EventBase<SurveyModel, MatrixRowAddedEvent>
- Implemented in:
- SurveyModel
An event that is raised on removing a row from Matrix Dynamic question.
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
:any
a removed row objectoptions.rowIndex
:number
a removed row index
- Type:
- EventBase<SurveyModel, MatrixRowRemovedEvent>
- Implemented in:
- SurveyModel
An event that is raised before removing a row from Matrix Dynamic question. You can disable removing and clear the 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.allow
:boolean
a boolean property. Set it tofalse
to disable the row removingoptions.row
:any
a row objectoptions.rowIndex
:number
a row index
- Type:
- EventBase<SurveyModel, MatrixRowRemovingEvent>
- Implemented in:
- SurveyModel
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
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
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
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.rootPanel
:any
options.parentPanel
:any
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
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
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.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
Use this event to save incomplete survey results. Enable the sendResultOnPageNext
property for this event to occur.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.
Refer to the following help topic for more information on the use case: Continue an Incomplete Survey.
- Type:
- EventBase<SurveyModel, {}>
- Implemented in:
- SurveyModel
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
An event that is raised on processing the text when it finds a text in brackets: {somevalue}
. By default, it uses the value of survey question values and variables.
For example, you may use the text processing in loading choices from the web. If your choicesByUrl.url
equals to "UrlToServiceToGetAllCities//",
you may set on this event options.value
to "all" or empty string when the "state" value/question is non selected by a user.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.value
:any
the value of the processing textoptions.isExists
:boolean
a boolean value. Set it totrue
if you want to use the value and set it tofalse
if you don'toptions.canProcess
:boolean
options.name
:string
the name of the processing value, for example, "state" in our exampleoptions.returnDisplayValue
:boolean
- Type:
- EventBase<SurveyModel, ProcessTextValueEvent>
- Implemented in:
- SurveyModel
Use this event to change the progress text in code.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.requiredAnsweredQuestionCount
:number
a number of required questions that have input(s) and an user has answeredoptions.requiredQuestionCount
:number
a number of required questions that have input(s). We do not count html or expression questionsoptions.answeredQuestionCount
:number
a number of questions that have input(s) and an user has answeredoptions.questionCount
:number
a number of questions that have input(s). We do not count html or expression questionsoptions.text
:string
a progress text, that SurveyJS will render in progress bar
- Type:
- EventBase<SurveyModel, ProgressTextEvent>
- Implemented in:
- SurveyModel
- See also:
- progressBarType
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 asnewValue
does.
- Type:
- EventBase<Base, any>
- Implemented in:
- Base
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.rootPanel
:any
options.parentPanel
:any
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
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
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
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
Use this event to control scrolling element to top. You can cancel the default behavior by setting options.cancel property to true.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.element
:ISurveyElement
an element that is going to be scrolled on topoptions.question
:Question
a question that is going to be scrolled on top. It can be null if options.page is not nulloptions.page
:PageModel
a page that is going to be scrolled on top. It can be null if options.question is not nulloptions.cancel
:boolean
set this property to true to cancel the default scrollingoptions.elementId
:string
the unique element DOM Id
- Type:
- EventBase<SurveyModel, ScrollingElementToTopEvent>
- Implemented in:
- SurveyModel
The event fires when it gets response from the api.surveyjs.io service on saving survey results. Use it to find out if the results have been saved successfully.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.response
:any
a response from the serviceoptions.request
:any
options.success
:boolean
it istrue
if the results has been sent to the service successfully
- Type:
- EventBase<SurveyModel, SendResultEvent>
- Implemented in:
- SurveyModel
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"]
.
- Type:
- EventBase<SurveyModel, ServerValidateQuestionsEvent>
- Implemented in:
- SurveyModel
- See also:
- onValidateQuestion * , onValidatePanel
An event that is raised before errors are assigned to a question. You may add/remove/modify errors for a question.
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
Use this event to change the visibility of an individual choice item in Checkbox, Dropdown, Radiogroup, 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.visible
:boolean
A Boolean value that specifies item visibility. Set it tofalse
to hide the item.options.item
:ItemValue
The choice item as specified in the choices array.
- Type:
- EventBase<SurveyModel, ShowingChoiceItemEvent>
- Implemented in:
- SurveyModel
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
Set this property tofalse
if you want to cancel the preview.options.allowShowPreview
:boolean
- Type:
- EventBase<SurveyModel, ShowingPreviewEvent>
- Implemented in:
- SurveyModel
- See also:
- showPreviewBeforeComplete * , showPreview * , cancelPreview
An event that is raised when the survey state
changes to "running"
.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.
- Type:
- EventBase<SurveyModel, {}>
- Implemented in:
- SurveyModel
- See also:
- firstPageIsStarted
Use this event to process the markdown text.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.name
:string
a property name is going to be renderedoptions.element
:Question | PanelModel | PageModel | SurveyModel
SurveyJS element (a question, panel, page, or survey) where the string is going to be renderedoptions.html
:string
an HTML content. It isnull
by default. Use this property to specify the HTML content rendered instead ofoptions.text
options.text
:string
a text that is going to be rendered
- Type:
- EventBase<SurveyModel, TextMarkdownEvent>
- Implemented in:
- SurveyModel
Use this event to specity render component name used for text rendering.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.name
:string
a property name is going to be renderedoptions.element
:Question | PanelModel | PageModel | SurveyModel
SurveyJS element (a question, panel, page, or survey) where the string is going to be renderedoptions.renderAs
:string
a component name used for text rendering
- Type:
- EventBase<SurveyModel, TextRenderAsEvent>
- Implemented in:
- SurveyModel
An event that is raised every second if the method startTimer
has been called.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.
- Type:
- EventBase<SurveyModel, {}>
- Implemented in:
- SurveyModel
- See also:
- startTimer * , timeSpent * , Page.timeSpent
An event that is raised before displaying a new information in the Timer Panel. Use it to change the default text.
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
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.
For more information about triggers, refer to the following help topic: Conditional Survey Logic (Triggers).
- Type:
- EventBase<SurveyModel, TriggerExecutedEvent>
- Implemented in:
- SurveyModel
- See also:
- triggers * , runTriggers
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.css
:string
a string with css classes divided by space. You can change itoptions.item
:ItemValue
a choice item of ItemValue type. You can get value or text choice properties as options.item.value or options.choice.text
- Type:
- EventBase<SurveyModel, UpdateChoiceItemCssEvent>
- Implemented in:
- SurveyModel
- See also:
- css
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.
- Type:
- EventBase<SurveyModel, UpdatePageCssClassesEvent>
- Implemented in:
- SurveyModel
- See also:
- css
An event that is raised before rendering a 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.
- Type:
- EventBase<SurveyModel, UpdatePanelCssClassesEvent>
- Implemented in:
- SurveyModel
- See also:
- css
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.
- Type:
- EventBase<SurveyModel, UpdateQuestionCssClassesEvent>
- Implemented in:
- SurveyModel
- See also:
- css
An event that is raised on uploading the file in QuestionFile when storeDataAsText
is set to false
. Use this event to change the uploaded file name or to prevent a particular file from being uploaded.
Parameters:
sender
:SurveyModel
A survey instance that raised the event.options.question
:QuestionFileModel
A File question instance for which the event is raised.options.name
:string
the question nameoptions.callback
:(status: string, data?: any) => any
a callback function to get the file upload status and the updloaded file contentoptions.files
:any[]
the Javascript File objects array to upload
- Type:
- EventBase<SurveyModel, UploadFilesEvent>
- Implemented in:
- SurveyModel
- See also:
- uploadFiles * , QuestionFileModel.storeDataAsText * , onDownloadFile * , onClearFiles
Use the this event to be notified when the survey finished validate questions on the current page. It commonly happens when a user try to go to the next page or complete the survey
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[]
the list of questions that have errorsoptions.errors
:SurveyError[]
the list of errors
- Type:
- EventBase<SurveyModel, ValidatedErrorsOnCurrentPageEvent>
- Implemented in:
- SurveyModel
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.
- Type:
- EventBase<SurveyModel, ValidatePanelEvent>
- Implemented in:
- SurveyModel
- See also:
- onValidateQuestion * , onServerValidateQuestions
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.
- Type:
- EventBase<SurveyModel, ValidateQuestionEvent>
- Implemented in:
- SurveyModel
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
Thename
of the question whose value is being changed. If you use thevalueName
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
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
Thename
of the question whose value is being changed. If you use thevalueName
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
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
Obsolete. Please use onQuestionVisibleChanged event.
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.
- Type:
- EventBase<SurveyModel, QuestionVisibleChangedEvent>
- Implemented in:
- SurveyModel
- See also:
- onQuestionVisibleChanged
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
Gets or sets the 'Next' button caption.
- 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:
- locale
Gets or sets the 'Prev' button caption.
- 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:
- locale
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
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
Navigates user to a previous page. If the current page is the first page, prevPage
returns false
. prevPage
does not perform any checks, required questions can be empty.
- Type:
- () => boolean
- Implemented in:
- SurveyModel
- See also:
- isFirstPage
Returns the HTML content, that is shown to a user that had completed the survey before.
- Type:
- string readonly
- Implemented in:
- SurveyModel
- See also:
- completedHtml * , cookieName
Returns the HTML content for the complete page.
- Type:
- string readonly
- Implemented in:
- SurveyModel
- See also:
- completedHtml
Returns the HTML content, that is shows when a survey loads the survey JSON.
- Type:
- string readonly
- Implemented in:
- SurveyModel
Gets or sets the type of info in the progress bar.
The following options are available:
pages
(default),questions
,requiredQuestions
,correctQuestions
,buttons
- 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 , buttons
- Implemented in:
- SurveyModel
Returns the progress that a user made while going through the survey. It depends from progressBarType property
- Type:
- number readonly
- Implemented in:
- SurveyModel
- See also:
- progressBarType
Gets or sets the question description position. The default value is underTitle
.
The following options are available:
underTitle
- show question description under the question title,underInput
- show question description under the question input instead of question title.
- 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
Gets or sets the error message position.
The following options are available:
top
- to show question error(s) over the question,bottom
- to show question error(s) under the 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
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:
- singlePage , standard , questionPerPage
- Implemented in:
- SurveyModel
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
Gets or sets the first question index. The first question index is '1' by default. You may start it from '100' or from 'A', by setting '100' or 'A' to this property. You can set the start index to "(1)" or "# A)" or "a)" to render question number as (1), # A) and a) accordingly.
- 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:
- Question.title * , View Demo
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
Set the pattern for question title. Default is "numTitleRequire", 1. What is your name? *, You can set it to numRequireTitle: 1. * What is your name? You can set it to requireNumTitle: * 1. What is your name? You can set it to numTitle (remove require symbol completely): 1. What is your name?
- 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
- See also:
- View Demo
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
Removes a page from a survey.
- Type:
- (page: PageModel) => void
- Parameters:
-
page, type: PageModel
- Implemented in:
- SurveyModel
Gets or sets the required question mark. The required question mark is a char or string that is rendered in the required questions' titles.
- 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
- See also:
- View Demo
Calculates a given expression and returns true
or false
.
- Type:
- (expression: string) => boolean
- Parameters:
-
expression, type: string
- Implemented in:
- SurveyModel
Calculates a given expression and returns a result value.
- Type:
- (expression: string) => any
- Parameters:
-
expression, type: string
- Implemented in:
- SurveyModel
Run all triggers that performs on value changed and not on moving to the next page.
- Type:
- () => void
- Implemented in:
- SurveyModel
Sends a survey result to the api.surveyjs.io service.
- Type:
- (postId?: string, clientId?: string, isPartialCompleted?: boolean) => void
- Parameters:
-
clientId, type: string ,
Typically a customer e-mail or an identifier
isPartialCompleted, type: boolean ,Set it to
true
if the survey is not completed yet and the results are intermediate
- Implemented in:
- SurveyModel
- See also:
- surveyPostId * , clientId
Specifies whether to save survey results when respondents swtich between pages. Handle the onPartialSend
event to implement the save operation.
Refer to the following help topic for more information on the use case: 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
Sets a comment value.
- Type:
- (name: string, newValue: string, locNotification?: any) => void
- Parameters:
-
name, type: string ,
A comment name.
newValue, type: string ,A new comment value.
locNotification, type: any
- Implemented in:
- SurveyModel
- See also:
- getComment
Set the cookie with cookieName
in user's browser. It is done automatically on survey complete if the cookieName
property value is not empty.
- Type:
- () => void
- Implemented in:
- SurveyModel
- See also:
- cookieName * , hasCookie * , deleteCookie
Sets the survey into design mode.
- Type:
- (value: boolean) => void
- Parameters:
-
value, type: boolean ,
use true to set the survey into the design mode.
- Implemented in:
- SurveyModel
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
Sets a question value (answer). It runs all triggers and conditions (visibleIf
properties).
Goes to the next page if goNextPageAutomatic
is true
and all questions on the current page are answered correctly.
- Type:
- (name: string, newQuestionValue: any, locNotification?: any, allowNotifyValueChanged?: boolean) => void
- Parameters:
-
name, type: string ,
A question name
newQuestionValue, type: anylocNotification, type: anyallowNotifyValueChanged, type: boolean
- Implemented in:
- SurveyModel
- See also:
- data * , getValue * , PageModel.visibleIf * , Question.visibleIf * , goNextPageAutomatic
Sets a variable value. Variable, unlike values, are not stored in the survey results.
- Type:
- (name: string, newValue: any) => void
- Parameters:
-
name, type: string ,
A variable name
newValue, type: any ,A variable new value
- Implemented in:
- SurveyModel
- See also:
- GetVariable
On finishing the survey the complete page is shown. Set the property to false
, to hide 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:
- data * , onComplete * , View Demo
Gets or sets whether to show all elements in the survey, regardless their visibility. The default value is false
.
- Type:
- boolean writable
- Implemented in:
- SurveyModel
Gets or sets whether the survey displays page numbers on pages titles.
- Type:
- boolean writable
This property is stored in the survey JSON definition and can be edited in the Survey Creator.
- Implemented in:
- SurveyModel
Gets or sets whether the Survey displays page titles. Set it to false
to hide 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
- See also:
- View Demo
Gets or sets whether the Survey displays "Prev" button in its pages. Set it to false
to prevent end-users from going back to their answers.
- 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
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
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.
- 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
Gets or sets the survey progress bar position.
The following options are available:
off
(default) - don't show progress bartop
- show progress bar in the topbottom
- show progress bar in the bottomboth
- show progress bar in both sides: top and bottom.
- 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 , top , bottom , both
- Implemented in:
- SurveyModel
Gets or sets a value that specifies how the question numbers are displayed.
The following options are available:
on
- display question numbersonpage
- display question numbers, start numbering on every pageoff
- turn off the numbering for questions titles
- 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
Gets or sets a timer panel position. The timer panel displays information about how much time an end user spends on a survey/page.
The available options:
top
- display timer panel in the top.bottom
- display timer panel in the bottom.none
- do not display a timer panel.
If the value is not equal to 'none', the survey calls the startTimer()
method on survey rendering.
- 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:
- showTimerPanelMode * , startTimer * , stopTimer
Gets or set a value that specifies whether the timer displays information for the page or for the entire survey.
The available options:
page
- show timer information for pagesurvey
- show timer information for survey
Use the onTimerPanelInfoText
event to change the default text.
- 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:
- all , page , survey
- Implemented in:
- SurveyModel
- See also:
- showTimerPanel * , onTimerPanelInfoText
Gets or sets whether the Survey displays survey title in its pages. Set it to false
to hide a survey title.
- 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:
- View Demo
Gets or sets the visibility of the table of contents.
Default value: false
- 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
Starts the survey. Changes the survey mode from "starting" to "running". Call this function if your survey has a start page, otherwise this function does nothing.
- Type:
- () => boolean
- Implemented in:
- SurveyModel
- See also:
- firstPageIsStarted
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
Gets or sets the 'Start' button caption.
The 'Start' button is shown on the started page. Set the firstPageIsStarted
property to true
, to display the started 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:
- firstPageIsStarted * , locale
Starts a timer that will calculate how much time end-user spends on the survey or on pages.
- Type:
- () => void
- Implemented in:
- SurveyModel
- See also:
- stopTimer * , timeSpent
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
Gets or sets whether the "Others" option text is stored as question comment.
By default the entered text in the "Others" input in the checkbox/radiogroup/dropdown is stored as "question name " + "-Comment"
. The value itself is "question name": "others"
.
Set this property to false
, to store the entered text directly in the "question name"
key.
- 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:
- commentSuffix
The identifier of a survey JSON schema to load from the 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
An identifier used to save survey results to the 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
Gets or sets whether to show the progress on saving/sending data into the api.surveyjs.io service.
- 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
Gets or sets a value that specifies how the survey updates its questions' text values.
The following options are available:
onBlur
(default) - the value is updated after an input loses the focus.onTyping
- update the value of text questions, "text" and "comment", on every key press.
Note, that setting to "onTyping" may lead to a performance degradation, in case you have many expressions in the survey.
- 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
Gets or set the time in seconds an end user spends on the survey.
- Type:
- number writable
- Implemented in:
- SurveyModel
- See also:
- startTimer * , PageModel.timeSpent
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
Gets or sets the position of the table of contents. Applies only when the table of contents is visible.
Possible values:
"left"
(default)"right"
- 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
Gets or sets a list of triggers in the survey.
- 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:
- SurveyTrigger
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
Uploads a file to server.
- Type:
- (question: QuestionFileModel, name: string, files: any[], uploadingCallback: (status: string, data: any) => any) => void
- Parameters:
-
question, type: QuestionFileModel ,
a file question object
name, type: string ,a question name
files, type: any[] ,files to upload
uploadingCallback, type: (status: string, data: any) => any ,a call back function to get the status on uploading the files
- Implemented in:
- SurveyModel
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 equalstrue
if the validation fails orfalse
otherwise.
- Implemented in:
- SurveyModel
- See also:
- validateCurrentPage * , validatePage
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 equalstrue
if the validation fails orfalse
otherwise.
- Implemented in:
- SurveyModel
- See also:
- currentPage * , validate * , validateCurrentPage
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 passundefined
to validate theactivePage
.onAsyncValidation, type: (hasErrors: boolean) => void ,Optional. Pass a callback function. It accepts a Boolean
hasErrors
parameter that equalstrue
if the validation fails orfalse
otherwise.
- Implemented in:
- SurveyModel
- See also:
- validate * , validateCurrentPage
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
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
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
Gets or sets a value that specifies how the survey width is calculated.
The available options:
static
- A survey has a fixed width that mostly depends upon the applied theme. Resizing a browser window does not affect the survey width.responsive
- A survey takes all available horizontal space. A survey stretches or shrinks horizonally according to the screen size.auto
- Depends on the 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
Copyright © 2023 Devsoft Baltic OÜ. All rights reserved.