Skip to main content

Parameters

Some question types in XLSForm have additional parameters that allow you to control the style or behavior of questions in a survey. In some cases, these parameters complement the appearances that a question type supports. Not all parameters are supported in all the submission apps (Survey123 Mobile, the Survey123 field app, and the Survey123 web app). For more information about app support, refer to the parameter tables below, which are organized by question type and the XLSForm column on the survey worksheet that accepts each parameter.

You can add multiple parameters for a question to the same column by separating the parameters with spaces. For example, a range question can have startColor, endColor, and color parameters in the body::esri:style column, as follows:

startColor=Orange endColor=White color=#FF6347

General

This section describes the parameters you can use in the bind::esri:parameters and body::esri:style XLSForm columns for multiple question types.

The following table describes the parameter you can use in the bind::esri:parameters XLSForm column for the text, integer, decimal, note, date, time, dateTime, select_one, select_multiple, geopoint, calculate, and hidden question types.

bind::esri:parameters

Parameter

Description

Submission app

calculationMode

Control when the calculation in a question is calculated.

Values: auto | manual | always | whenEmpty

Examples:

calculationMode=manual
calculationMode=always

Web app

Field app

The following table describes the parameter you can use in the body::esri:style XLSForm column for the text, integer, decimal, select_one (with autocomplete appearance), select_multiple (with autocomplete appearance)*, and barcode question types.

body::esri:style

Parameter

Description

Submission app

placeholderText

Specify the text that appears in the question's input area when the question is empty.

Values: @[hint] | @[guidance_hint]

Examples:

placeholderText=@[hint]
placeholderText=@[guidance_hint]

Survey123 Mobile

Field app

*Supported by Survey123 Mobile only.

Audio

The following table describes the parameters you can use in the bind::esri:parameters XLSForm column for the audio question type.

bind::esri:parameters

Parameter

Description

Submission app

codec

Specify the preferred codec for an audio recording. Multiple codecs can be provided, separated by commas. The first codec compatible with the device will be used.

Value: <codec name>

Example:

codec=amr-nb,aac

Survey123 Mobile

Field app

fileName

Specify the file name.

Values: <expression>

Examples:

fileName=concat("JobID-", ${job_id})
fileName=concat(${asset_id}, "_",
  format-date(now(), "%Y%m%d%H%M%S"))

Web app

max-duration

Specify the maximum duration in seconds for an audio recording. The default duration in the web app is 600 (10 minutes).

Value: <seconds>

Example:

max-duration=45

Survey123 Mobile

Web app

Field app

max-size

Specify the maximum file size in megabytes for an audio recording. The default size in the field app is 10 MB.

Value: <megabytes>

Example:

max-size=5

Survey123 Mobile

Field app

Barcode

The following table describes the parameter you can use in the body::esri:style XLSForm column for the barcode question type.

body::esri:style

Parameter

Description

Submission app

barcodeType

Specify the types of barcodes users can scan. Multiple types can be provided, separated by commas. When the barcodeType parameter is not provided, all supported barcode types can be scanned except aztec, code39, datamatrix, maxicode, and pdf417.

Values: all | 1d | 2d | <barcode types>

  • all—All supported types except code39 and pdf417.

  • 1d—All one-dimensional types except code39.

  • 2d—All two-dimensional types except pdf417.

One-dimensional types: codabar | code128 | code39 | code93 | ean13 | ean8 | itf | upca | upce | upceanextension

Two-dimensional types: aztec | datamatrix | maxicode | pdf417 | qrcode | rss14 | rssexpanded

Examples:

barcodeType=qrcode,aztec,code128
barcodeType=ean8,itf
barcodeType=2d
barcodeType=pdf417

Field app

File

The following table describes the parameters you can use in the bind::esri:parameters XLSForm column for the file question type.

bind::esri:parameters

Parameter

Description

Submission app

fileName

Specify the file name.

Values: <expression>

Examples:

fileName=concat("JobID-", ${job_id})
fileName=concat(${asset_id}, "_",
  format-date(now(), "%Y%m%d%H%M%S"))

Web app

max-size

Specify the maximum file size in megabytes. The default is 10 MB.

Value: <megabytes>

Example:

max-size=5

Web app

Groups

The following table describes the parameters you can use in the body::esri:style XLSForm column for the begin group question type.

body::esri:style

Parameter

Description

Submission app

backgroundColor

borderColor

Set the background and border colors for a group or page. For more information, see Group, page, and repeat colors.

Values: <HTML color name> | <hex color code>

Examples:

backgroundColor=LightBlue
borderColor=#4682B4
backgroundColor=#C7FFC7 borderColor=#3C6D9E

Survey123 Mobile

Field app

layout

Set the grid layout style for a group.

Values: dynamic-grid | fixed-grid

Example:

layout=fixed-grid

Field app

Images

This section describes the parameters you can use in the specified XLSForm columns for the image question type.

The following table describes the parameters you can use in the bind::esri:parameters XLSForm column.

bind::esri:parameters

Parameter

Description

Submission app

allowAdds

Disable the addition of new images when editing existing records.

Value: false

Example:

allowAdds=false

Field app

fileName

Specify the file name.

Values: <expression>

Examples:

fileName=concat("JobID-", ${job_id})
fileName=concat(${asset_id}, "_",
  format-date(now(), "%Y%m%d%H%M%S"))

Web app

Field app

max-size

Specify the maximum file size in megabytes. The default is 10 MB.

Value: <megabytes>

Example:

max-size=5

Web app

smartAnnotation

For an image question with annotate appearance, automatically generates annotation graphics of labels and bounding boxes around the detected objects. Append these properties to define the style and formatting of the annotation.

Required property: <model_name>

Optional properties: minScore | cameraPreview | label | class | boundingBoxes | outlineWidth | fontSize | font | bold | italic

Examples:

smartAnnotation=modelname
  &cameraPreview=true&minScore=0.52
smartAnnotation=modelname&
  cameraPreview=true&minScore=0.52
  &class=classname1,classname2
  &label=false&bold=true

Field app

smartAttributes

Perform object detection or image classification and use the EXIF results in your survey.

Required property: <model_name>

Optional properties: minScore | cameraPreview | label | class

Examples:

smartAttributes=modelname
  &cameraPreview=true&minScore=0.45
smartAttributes=modelname
  &cameraPreview=true
  &class=classname1,classname2
  &label=false

Field app

redaction

Automatically generate or manually add bounding boxes and apply redacting effects on the target region.

Required property: <model_name> | @faces | @manual

Optional properties: minScore | cameraPreview | label | class | effect | symbol | fillColor | scale

Examples:

redaction=modelname
  &cameraPreview=true&effect=blur
redaction=@manual&effect=blockout
redaction=@faces&cameraPreview=true
  &class=classname1,classname2
  &label=false@effect=symbol&symbol=🐻

Field app

watermark

topLeftWatermark

topCenterWatermark

topRightWatermark

leftCenterWatermark

centerWatermark

rightCenterWatermark

bottomLeftWatermark

bottomCenterWatermark

bottomRightWatermark

Specify the position of an image watermark. Append properties to define the contents and formatting. For more information, see Watermarks.

Properties: text | color | outlineColor | outlineWidth | haloColor | size | font | bold | italic | margin | image | imageSize

Examples:

watermark="Example Text
  &outlineColor=White"
bottomLeftWatermark="Example Text
  &bold=true"
topRightWatermark="@[latitude longitude]
  &size=20"

Field app

The following table describes the parameters you can use in the body::esri:style XLSForm column for the image question type.

body::esri:style

Parameter

Description

Submission app

allowRename

Specify whether users can manually edit the file name.

Values: true | false

Example:

allowRename=false

Field app

fileNameVisible

Specify whether the file name is visible in the survey.

Values: true | false

Example:

fileNameVisible=true

Field app

footerText

For an image question with signature appearance, specify the text to display at the bottom of the signature pop-up. If no value is specified, the question's guidance hint will appear below the signature. This can be changed to the question's hint by using footerText=@[hint].

Values: <none> | @[hint]

Examples:

footerText
footerText=@[hint]

Survey123 Mobile

Field app

method

Specify the capture method for an image question. The map value is only supported for image questions with annotate appearance.

Values: browse | camera | map

Examples:

method=camera
method=map
method=browse,camera,map

Web app

Field app

palette

For an image question with draw or annotate appearance, specify a custom drawing tools palette.

Value: <palette name>

Example:

palette=SiteLayout

Field app

previewHeight

Set the height of the image preview after the image is selected. Use previewHeight=0 if you want your image preview to be of maximum size without unnecessary blank space.

Values: <lines> | <lines>lines | <percentage of screen height>% | <pixels>pixels

Examples:

previewHeight=3lines
previewHeight=120pixels

Field app

The following table describes the parameter you can use in the parameters XLSForm column for the image question type.

parameters

Parameter

Description

Submission app

max-pixels

For an image question, set the maximum size of the image on the longest edge, preserving the original aspect ratio.

For an image question with signature appearance, set the maximum width for the signature pop-up.

For an image question with draw appearance, set the canvas to a square (1:1) image.

Value: <pixels>

Examples:

max-pixels=1500
max-pixels=400

Web app

Field app

Map questions

The following table describes the parameters you can use in the specified XLSForm columns for the geopoint, geotrace, and geoshape question types.

The following table describes the parameter you can use in the bind::esri:parameters XLSForm column.

bind::esri:parameters

Parameter

Description

Submission app

geocode

Set the locator to return geocoded results from.

Value: <locator item ID>

Example:

geocode=36ff9e8c13e042a58cfce4ad87f55d19

Survey123 Mobile

Web app

Field app

The following table describes the parameters you can use in the body::esri:style XLSForm column for the geopoint, geotrace, and geoshape question types.

body::esri:style

Parameter

Description

Submission app

height

Set the height of the map preview.

Values: <lines> | <lines>lines | <percentage of screen height>% | <pixels>pixels

Examples:

previewHeight=6lines
previewHeight=250pixels

Field app

lineColor2

fillColor3

Specify the line and fill colors for the line or polygon feature. This applies to the map preview in Survey123 only. For more information, see Geometry symbology.

Values: <HTML color name> | <hex color code>

Example:

lineColor=Black
fillColor=#9EFFF5

Survey123 Mobile

Field app

lineWidth 2

Specify the line width in pixels for the line or polygon feature. This applies to the map preview in Survey123 only.

Value: <pixels>

Examples:

lineWidth=3

Survey123 Mobile

Field app

map

Set a default basemap.

Values: <map name> | <map item ID>

Examples:

map="World Topography"
map=de26a3cf4cc9451298ea173c4b324736

Web app

Field app

mapTools

Control the map tools that are available for geopoint, geotrace, and geoshape questions.

Values: search | mapSwitcher | zoom | home | locate

Examples:

mapTools=zoom
mapTools=search,locate

Field app

method 2

Specify the capture method. When using the vertex method, additional parameters can be set.

Values: sketch | vertex

Additional values for vertex, applicable only in the field app: streaming | beep | haptic | edit

Examples:

method=vertex
method=vertex,streaming
method=vertex,streaming,haptic

Web app

Field app

minCaptureZoomLevel

Specify the minimum level at which geometry can be captured.

Value: <integer>

Example:

minCaptureZoomLevel=17

Web app

overlay

Display point locations from the first geopoint question within a repeat on any other geopoint, geoshape, or geotrace question in your survey. Append properties to define the contents and style.

Value: <repeat name>

Properties: view | preview | icon | iconColor | iconOutlineColor | iconSize | label | labelColor | labelOutlineColor | fontSize

Examples:

overlay=campsites&preview=true
overlay=hydrants&label=asset_id&icon=hydrant&iconColor=Red

Field app

precision

Specify the number of decimal places that will be both captured in the map question and shown in the individual response panel in the survey. When this parameter is not set, all available decimal places are captured in the map question but only six decimal places will be shown in the individual response panel.

Value: <integer>

Example:

precision=4

Web app

snapMode

Specify snapping behavior. Points can be snapped to other features, and lines and polygons can be snapped to other features or themselves. Only available when method=vertex.

Values: feature | self 2

Example:

snapMode=feature
snapMode=self
snapMode=self,feature

Web app

symbol 1

Specify a .png file to use as the point marker on the map. Append properties to define the position and scale.

Value: <file name>.png

Properties: x | y | scale

Example:

symbol=meter.png?x=0.6&y=0.1&scale=1.5

Field app

1—Supported by the geopoint question type only.

2—Supported by the geoshape and geotrace question types only.

3—Supported by the geoshape question type only.

Multiple-choice questions

The following table describes the parameter you can use in the parameters XLSForm column for the select_one, select_multiple, and rank question types.

parameters

Parameter

Description

Submission app

randomize

Randomize the order of choices in a choice list.

Values: true

Example:

randomize=true

Web app

Field app

Range

This section describes the parameters you can use in the specified XLSForm columns for the range question type. When combining, parameters must be separated by a space.

The following table describes the parameters you can use in the body::esri:style XLSForm column. For more information, see Style options.

body::esri:style

Parameter

Description

Submission app

startColor

endColor

color

Specify colors for the range slider:

  • Color of the slider at the start of the range.

  • Color of the slider at the end of the range.

  • Color that fills the space between the start of the slider and the selected value.

Values: <HTML color name> | <hex color code>

Examples:

startColor=Blue endColor=Red
startColor=Orange endColor=White color=#FF6347
endColor=#262626 color=Yellow

Survey123 Mobile

Web app

Field app

The following table describes the parameters you can use in the parameters XLSForm column for the range question type. For more information, see Range slider parameters.

parameters

Parameter

Description

Submission app

start

end

step

Specify the start, end, and step values of the range slider.

Values: <integer> | <decimal>

Examples:

start=0 end=50 step=5
start=10.25 end=1 step=0.25

Survey123 Mobile

Web app

Field app

Repeats

This section describes the parameters you can use in the specified XLSForm columns for the begin repeat question type.

The following table describes the parameters you can use in the bind::esri:parameters XLSForm column.

bind::esri:parameters

Parameter

Description

Submission app

allowAdds

Allow new repeat records to be added.

Values: true | false

Example:

allowAdds=true

Field app

allowUpdates

Allow existing repeat records to be modified.

Values: true | false

Example:

allowUpdates=false

Field app

query

Allow existing repeat records to be shown in the form. Specify additional query parameters to filter the available records.

Values: <none> | "SQL statement"

Examples:

query
query="severity='high'"

Field app

The following table describes the parameters you can use in the body::esri:style XLSForm column for the begin repeat question type.

body::esri:style

Parameter

Description

Submission app

backgroundColor

borderColor

Set the background and border colors for a repeat. For more information, see Group, page, and repeat colors.

Values: <HTML color name> | <hex color code>

Examples:

backgroundColor=LightBlue
borderColor=#4682B4
backgroundColor=#C7FFC7 borderColor=#3C6D9E

Survey123 Mobile

Field app

addRecordMode

For a repeat with tabular appearance, specify the mode for the Add record button and the Copy to new record option in the tabular view. The default is row. When the value is row, the new record is appended to the tabular view. When the value is form, the new record is opened in the form view.

Values: row | form

Example:

addRecordMode=form

Survey123 Mobile

editInFormView

For a repeat with tabular appearance, show or hide the Edit in form view option in the tabular view. The default is true.

Note:

When the repeat has errors, the Edit in form view option is enabled even when the editInFormView parameter is set to false.

Values: true | false

Example:

editInFormView=false

Survey123 Mobile

copyToNewRecord

For a repeat with tabular appearance, show or hide the Copy to new record option in the tabular view. This option allows users to duplicate a record in the repeat. The default is true. The addRecordMode parameter determines how the duplicate record is added.

Values: true | false

Example:

copyToNewRecord=true

Survey123 Mobile

editInTabularView

For a repeat with tabular appearance, enable or disable editing in the tabular view. The default is true. When the value is false, all cells in the tabular view are read-only.

Values: true | false

Example:

editInTabularView=false

Survey123 Mobile

The following table describes the parameters you can use in the body::esri:style XLSForm column for questions in tabular repeats.

body::esri:style

Parameter

Description

Submission app

showInTabularView

For a question in a repeat with tabular appearance, show the question as a column in the tabular view. The default is false.

Values: true | false

Example:

showInTabularView=true

Survey123 Mobile

includeInCopy

For a question in a repeat with tabular appearance, specify whether the question's value is copied to new records when using the Copy to new record option. The default is true.

Values: true | false

Example:

includeInCopy=false

Survey123 Mobile

Text

This section describes the parameters you can use in the specified XLSForm columns for the text question type.

The following table describes the parameters you can use in the bind::esri:parameters XLSForm column.

bind::esri:parameters

Parameter

Description

Submission app

geocode

For a text question with geocode appearance, set the locator to return geocoded results from when using geocode appearance.

Value: <locator item ID>

Example:

geocode=36ff9e8c13e042a58cfce4ad87f55d19

Survey123 Mobile

Web app

Field app

The following table describes the parameters you can use in the body::esri:style XLSForm column for the text question type.

body::esri:style

Parameter

Description

Submission app

defaultHeight

For a text question with multiline appearance, set the initial height of the text box. The height of the text box will increase to accommodate the answer text.

Value: <number of lines>

Example:

defaultHeight=5

Field app

indicator

For a text question with geocode appearance, allow geocoded results to show the direction and distance from the current device location.

Values: direction | distance | none

Examples:

indicator=none
indicator=direction
indicator=direction,distance

Survey123 Mobile

Field app

maxResults

For a text question with geocode appearance, specify the maximum number of results to be returned. The default is 6.

Value: <number of results>

Example:

maxResults=10

Survey123 Mobile

Web app

Field app

proximity

For a text question with geocode appearance, specify whether the geocoded results only show results within a certain radius of the device's location.

Values: <distance>m | km | ft | mi | yd

Examples:

proximity=3km
proximity=1000ft

Survey123 Mobile

Field app

suggestions

For a text question with geocode appearance, change how suggestions are populated. The default is yes.

Values: yes | no

Example:

suggestions=no

Survey123 Mobile

Field app

Rangefinder

The following table describes the parameter you can use in the bind::esri:parameters XLSForm column for the text, integer, and decimal question types to retrieve values from a rangefinder.

bind::esri:parameters

Parameter

Description

Submission app

measurement

For a text, decimal, or integer question with rangefinder appearance, set which measurements will be stored in the question. Enclose the list of values in quotation marks if values include spaces.

Values: height | azimuth | horizontalDistance | slopeDistance | inclination | multipleHeights

Examples:

measurement=height
measurement=height,azimuth,horizontalDistance
measurement="multipleHeights,Height 1,Height 2"

Field app