XLSForm 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. The tables below provide an overview of the parameters you can use in XLSForm, and the column on the survey worksheet that accepts each parameter. Not all parameters are supported in both the ArcGIS Survey123 field app and the web app. For more information about field app and web app support, refer to the documentation topic for each parameter.

You can add multiple parameters to the same column by separating the parameters with spaces. For example, a begin repeat question can have both backgroundColor and borderColor parameters in the body::esri:style column, as follows:

backgroundColor=LightBlue borderColor=#17425E

For some parameters, you can append additional properties using ampersands. For example, the symbol parameter for a geopoint question can have x, y, and scale properties, as follows:

symbol=hydrant.png&x=0.2&y=0.7&scale=2

General

The following table contains the XLSForm parameters you can use with various question types. Refer to the description for each parameter for the list of question types that support it. These parameters are only supported in the field app.

XLSForm columnParameterDescription

bind::esri:parameters

calculationMode

Control when the calculation in a question is calculated.

Question types: text | decimal | integer | note | date | time | dateTime | select_one | select_multiple | geopoint | calculate | hidden

Values: auto | manual | always | whenEmpty

Examples:

calculationMode=manual
calculationMode=always

body::esri:style

placeholderText

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

Question types: text | integer | decimal | select_one (with autocomplete appearance) | barcode

Values: @[hint] | @[guidance_hint]

Examples:

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

Audio

The following table contains the XLSForm parameters you can use with the audio question type. These parameters are only supported in the field app.

XLSForm columnParameterDescription

bind::esri:parameters

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

max-duration

Specify the maximum duration in seconds for an audio recording.

Value: <seconds>

Example:

max-duration=45

max-size

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

Value: <megabytes>

Example:

max-size=5

File

The following table contains the XLSForm parameters you can use with the file question type. This parameter is supported in the field app and web app.

XLSForm columnParameterDescription

bind::esri:parameters

max-size

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

Value: <megabytes>

Example:

max-size=20

Groups

The following table contains the XLSForm parameters you can use with the begin group question type. These parameters are only supported in the field app.

XLSForm columnParameterDescription

body::esri:style

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

layout

Set the grid layout style for a group.

Values: dynamic-grid | fixed-grid

Example:

layout=fixed-grid

Images

The following table contains the XLSForm parameters you can use with the image question type. These parameters are only supported in the field app unless indicated otherwise in the description.

XLSForm columnParameterDescription

bind::esri:parameters

allowAdds

Disable the addition of new images when editing existing records.

Value: false

Example:

allowAdds=false

fileName

Specify the file name.

Values: <expression>

This parameter is also supported in the web app.

Examples:

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

max-size

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

Value: <megabytes>

This parameter is also supported in the web app.

Example:

max-size=20

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"

body::esri:style

allowRename

Specify if users can manually edit the file name.

Values: true | false

Example:

allowRename=false

fileNameVisible

Specify if the file name is visible in the survey.

Values: true | false

Example:

fileNameVisible=true

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]

method

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

This parameter is also supported in the web app.

Values: browse | camera | map

Examples:

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

palette

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

Value: <palette name>

Example:

palette=SiteLayout

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

parameters

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.

This parameter is also supported in the web app.

Value: <pixels>

Examples:

max-pixels=1500
max-pixels=400

Map questions

The following table contains the XLSForm parameters you can use with the geopoint, geotrace, and geoshape question types. These parameters are only supported in the field app unless indicated otherwise in the description.

XLSForm columnParameterDescription

body::esri:style

height

Set the height of the map preview.

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

Examples:

previewHeight=6lines
previewHeight=250pixels

lineColor²

fillColor³

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 Style options.

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

Example:

lineColor=Black 
fillColor=#9EFFFF5

lineWidth²

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

map

Set a default basemap.

This parameter is also supported in the web app.

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

Examples:

map="World Topography"
map=de26a3cf4cc9451298ea173c4b324736

method²

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

This parameter is also supported in the web app.

Values: sketch | vertex

Additional values for vertex: streaming | beep | haptic | edit

Examples:

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

minCaptureZoomLevel

Specify the minimum level at which geometry can be captured.

This parameter is only supported in the web app.

Value: <integer>

Example:

minCaptureZoomLevel=17

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

snapMode

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

This parameter is only supported in the web app.

Values: feature | self²

Example:

snapMode=feature
snapMode=self
snapMode=self,feature

symbol¹

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

¹Supported by the geopoint question type only.

²Supported by the geoshape and geotrace question types only.

³Supported by the geoshape question type only.

Multiple choice questions

The following table contains the XLSForm parameters you can use with the select_one, select_multiple, and rank question types. This parameter is supported in the field app and web app.

XLSForm columnParameterDescription

parameters

randomize

Randomize the order of choices in a choice list.

Values: true

Example:

randomize=true

Range

The following table contains the XLSForm parameters you can use with the range question type. These parameters are only supported in the field app.

XLSForm columnParameterDescription

body::esri:style

startColor

endColor

color

Specify the color of the slider at the start and end of the range. Use the color parameter to specify the color that is used to fill the space between the start of the slider and the selected value. Parameters must be separated by a space. For more information, see Style options.

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

Examples:

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

parameters

start

end

step

Specify the start, end, and step values of the range slider. Parameters must be separated by a space. For more information, see Range parameters.

Values: <integer> | <decimal>

Examples:

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

Repeats

The following table contains the XLSForm parameters you can use with the begin repeat question type. These parameters are only supported in the field app.

XLSForm columnParameterDescription

bind::esri:parameters

allowAdds

Allow new repeat records to be added.

Values: true | false

Example:

allowAdds=true

allowUpdates

Allow existing repeat records to be modified.

Values: true | false

Example:

allowUpdates=false

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'"

body::esri:style

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

Text

The following table contains the XLSForm parameters you can use with the text question type. These parameters are only supported in the field app unless indicated otherwise in the description.

XLSForm columnParameterDescription

bind::esri:parameters

geocode

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

This parameter is also supported in the web app.

Value: <locator item ID>

Example:

geocode=36ff9e8c13e042a58cfce4ad87f55d19

body::esri:style

defaultHeight

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

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

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>

This parameter is also supported in the web app.

Example:

maxResults=10

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

suggestions

For a text question with geocode appearance, disable the suggestions that appear as the user types a search.

Values: no

Example:

suggestions=no