responseOptions

Experiments Surveys & forms In surveys it lists the answer choices; on experiment trials the same cell configures the response widget (slider, box, clicks, mic, sort).

A column with several distinct uses: what it means depends on the trial’s responseType (and, for surveys/forms, on the question type). It carries: (a) the list of answer choices for form/survey questions and label responses, (b) slider configuration, (c) input-box constraints, (d) click-response settings, (e) microphone recording settings, and (f) response-flow flags (min/max multiple responses, waitResponseWindow, waitTimeout, noButton).

Syntax

For a survey or form question, list the answer choices separated by ;: Never;Sometimes;Often. That is the most common use.

Everything in the cell is written as ;-separated values and flags. What those values mean depends on the trial’s responseType:

• Form/survey choices (responseType = radio, checkboxes, dropdown, rank, likert, or a matrix built with responseRows): ;-separated choice texts; empty segments are ignored and %var% variables are replaced. A choice ending in :exclusive becomes a mutually exclusive checkbox option, with the keyword removed from the displayed text.
• Slider (responseType=slider): write the range as min_max, for example 0_100. The cell works the same way on experiment trials and in form questions. Empty ; segments are ignored. The first segment sets the scale, with its parts separated by _:
  • max: one number greater than 0 gives 0 to max, step 1.
  • min_max: min must be less than max.
  • max_step: when the first number is greater than the second and greater than 0, the scale runs from 0 to max in that step (100_5 is 0 to 100 in steps of 5).
  • min_max_step: min less than max, and max greater than step (0_50_10).
  • Numbers can be negative or decimal (-10_10_0.5). A step of 0 or less becomes 1.
  • An endpoint can carry a label in parentheses: 0(low)_10(high). A space before the parenthesis is allowed, and a missing closing parenthesis is accepted: 1(Strongly disagree_10(Strongly agree) is 1 to 10 with both labels. The label ends at the last closing parenthesis, and text after it is not shown: 0(Strongly Disagree)_10(Strongly Agree)1 shows Strongly Agree.
  • A number followed by a unit is still a number, and it is shown as written: 0%_100% works like 0(0%)_100(100%), and 0 cm_10 cm is 0 to 10 with the labels 0 cm and 10 cm. The unit can be written in any case, with or without a space before it, and can also go on the step and on the start value (0%_100%_5%;50% is 0 to 100, step 5, start 50). Only these units count: %, ‰, °, °C, °F, px, mm, cm, km, m, in, ft, ms, s, sec, secs, min, mins, h, hr, hrs, kg, g, lb, lbs, ml, l, kcal, cal, bpm, hz, db. Any other text after a number (2 or fewer, 1st, 1 = never) makes that part a label, so the whole segment becomes a label list.
  • Three numbers in any other order, more than three parts, or any part that is not a number give a label list, with positions 1 to n. Each label is shown and recorded as written, spaces included (Never_ Rarely _Often has the label Rarely). A part of only spaces between two other parts is a position without a label: angry_ _ _neutral_ _ _happy has 7 positions. An empty part (Not sure__A little pleasant) is dropped.
  • In a label list, a part written N(label) shows the label and records the part as written: 1(Not at all worried)_2_3_4(Neutral)_5 shows Neutral at position 4 and records 4(Neutral). A space before the parenthesis reads the same as none: 1 (Never)_2 (Rarely)_3 (Often) shows Never and records 1 (Never). A part without parentheses shows and records its text.
  • The second segment is the start value, unless it is a flag. Put the start value before any flags: 0_100;50;hideGrid starts at 50, but 0_100;hideGrid;50 starts at 0. The trial file editor warns about a start value after a flag. On a numeric slider it is a number, with an optional unit, kept inside the range (0_100;150 starts at 100); any other text leaves the start at the minimum. On a label slider it is the item as written, its shown label or, for a part written N(label), its number, with surrounding spaces ignored: for 1(start)_30(thirty)_50(half)_100(end), the start values 100(end), end and 100 all start at position 4, and Never_Rarely_Sometimes; Rarely starts at position 2. A number equal to one of these also matches (1_3_5_7;5 starts at position 3). A start value that matches no item (Never_Rarely_Sometimes;2) starts at position 1.
  • Flags: hideValue, hideStart, hideGrid, hideMinMax, hideLabels, removeFill and noButton, spelled exactly like this. A flag can go in any segment, even as a _ part of the first one (0_10_noButton;5), and a cell can hold flags only (hideGrid;hideStart;hideValue).
  • An empty cell, a single word (worst-worse-expected-better-best), 5_5, -5_-10 or any other first segment that fits none of these forms gives the default scale: 0 to 100, step 1, start 0.
• Input boxes (responseType=box / box*N): option:value pairs separated by ;, namely sum:N, min:N, max:N and width:N, plus HTML input attributes such as pattern:"[0-9]+", placeholder:... and maxlength:.... type: accepts color, date, datetime-local, email, month, number, range, tel, text, time, url and week; quotes around a value are removed.
• Box prefix and suffix (responseType=box / box*N, on test trials and in forms): prefix:TEXT shows TEXT before the input and suffix:TEXT shows TEXT after it, for example prefix:$;suffix:%. The key can be written in any case, the text is everything after the first colon, and an empty text shows nothing. Only a segment that starts with prefix: or suffix: counts, so placeholder:prefix: none stays a placeholder. The text is only displayed: the response records what the participant typed, without the prefix or suffix. Screen readers announce the text as the description of the input. These segments never act as other box options, so suffix:required does not make the box required.
• Clicks (responseType=clicks): flags can be written in any case: min:N/max:N (multi-click selection), pixel (report pixel coordinates), origin:center|topright|bottomleft|bottomright (shift the coordinate origin), grid(RxC) (bucket clicks into an RxC grid; ignored when pixel is present).
• Mic (responseType=mic): flags can be written in any case: save or save:MS (save a recording anchored on the voice onset; 1000 ms by default), save:all (record the entire trial from trial start; implies start:trial), save:no (never save), start:trial (start recording at trial start instead of at voice onset), prevoice:N (keep N ms of audio before the detected voice onset), noHide, hideRec. save:all, save:no, start:trial and prevoice:N must each be their own ;-separated segment; save, noHide and hideRec are recognized anywhere in the cell.
• Sort trials: ;-separated stimulus positions (2;4;5) or a lower:upper range (2:5) saying which stimuli are sortable.
• Keyboard and default trials: min:N / max:N (spaces around : are allowed) let the participant give several key responses.
• Flow flags (any responseType): waitResponseWindow keeps the trial open until the response window closes even after a response; waitTimeout prevents the response window’s timeout from closing it.
• Scoring labels: with a score column, the ;-separated segments here are the response values that map, in order, onto the ;-separated numbers in score.

Options

Token / segment	Applies to	Effect
text;text;...	forms, label, rank, likert, matrix	Choice list, order = display order (unless responseOptionsRandom)
choice:exclusive	checkboxes	Exclusive option (unchecks/blocks others)
max	slider	Range 0 to max, step 1; max must be greater than 0
min_max, max_step, min_max_step	slider	Numeric range and step (default step 1; a step of 0 or less becomes 1)
N(label) endpoints	slider	Endpoint labels: 0(not at all)_10(very); the closing parenthesis may be missing, and text after it is not shown
N with a unit, e.g. 0%_100%, 0 cm_10 cm	slider	Numeric endpoints shown as written (0% is 0(0%)); only the units listed under Syntax count
lab1_lab2_lab3	slider	Discrete labeled slider, positions 1..n; labels shown and recorded as written
N(label) as a list part	slider	Shows the label, records the part as written (4(Neutral)); responseCode is the position
number or label in the second segment	slider	Start position: a number (unit allowed) kept inside the range, or a list item as written (100(end)), its shown label (end), its number (100), or a number equal to one of them; a start value after a flag is ignored
hideValue	slider	Never show tooltip value
hideStart	slider	Hide handle until touched; untouched slider records NA, on test trials and in forms
hideGrid, hideMinMax, hideLabels	slider	Hide the respective chrome
removeFill	slider (test trials and forms)	Hide the filled bar
noButton	slider (test trials)	No Next button; the trial ends about 100 ms after the first finished interaction (pointer release or key release). No effect in forms
sum:N	box	All boxes must sum to N; boxes become type=number
min:N / max:N	box	Per-box numeric bounds; boxes become type=number
width:N	box	Box width in px
attr:value (e.g. pattern:"\d+", type:email, placeholder:x, maxlength:5)	box	Set as HTML input attribute
prefix:TEXT / suffix:TEXT	box (test trials and forms)	Text shown before / after the input, e.g. prefix:$, suffix:%; display only, not saved with the response
min:N / max:N	keyboard/default trials	Multiple responses: confirm after >=min, auto-end at max
min:N / max:N	clicks	Multi-click selection with Confirm button
N (standalone segment)	clicks	No effect; use min:/max: instead (see Tips & gotchas)
pixel	clicks	Response is stim_topxleft pixel position
origin:center/topright/bottomleft/bottomright	clicks + pixel	Shift coordinate origin; only works when origin: is the sole x:y pair in the cell (see Tips & gotchas)
grid(RxC)	clicks	Response bucketed to grid cell
save, save:MS	mic	Save an onset-anchored recording; MS = duration in ms (default 1000)
save:all	mic	Record the whole trial from trial start (forces start:trial); without buttons, keyboard or a responseWindow timeout the trial can never end
save:no	mic	Never save the recording, even if another segment contains save
start:trial	mic	Start recording at trial start instead of at voice onset
prevoice:N	mic	Keep N ms of audio before the detected voice onset in the saved file
noHide, hideRec	mic	Keep stimuli visible / hide the REC-waiting indicator; only unsaved voice-key trials ever hide stimuli, saved and start-at-trial recordings stay visible
2;4;5 or 2:5	sort	Which stimulus indices are sortable
waitResponseWindow	any	Do not end trial before the response window closes
waitTimeout	any	Response-window timeout does not close the trial
left blank	all	No options

Defaults & missing values

• With no responseOptions column, or with the cell left blank, the trial falls back to the plain behavior of its response type: no answer choices, no extra flags, no multiple responses, and nothing recorded from the microphone.
• Form question types that need choices (radio, checkboxes, dropdown, rank, likert) should always fill this column in. Left blank, the question has nothing for the participant to pick.
• Slider defaults: a numeric scale from 0 to 100, step 1, start 0, no labels, and none of the flags apply. A valid range starts at its minimum and a label list at position 1; only a start value or a flag changes that.
• Untouched slider on a test or practice trial: the recorded response is the start value. With hideStart an untouched slider records NA instead, and when every slider row of the trial is untouched the whole response is one NA, not NA;NA. responseCode is recorded only when the trial ends through the Next button or noButton: the number on a numeric slider, the position (1..n) on a label slider, and NA for an untouched hideStart slider. Practice trials record no responseCode. A trial button records the values followed by ; and the button number, and a response window timeout records the values followed by ;timeout, both without responseCode.
• Untouched slider in a form: NA, with or without hideStart. A slider the participant deliberately sets to 0 records 0.
• Sort trials with the cell left blank have no sortable stimuli.

Works with

• responseType: decides which of this column’s meanings applies, both on test trials and in form questions.
• responseOptionsRandom: any value shuffles the choice order shown to the participant; responseCode in the results still counts positions in the ORIGINAL order you wrote here. It has no effect on a slider.
• responseRows: turns choices into matrix columns, one row per responseRows entry. On a slider test trial each row label gets its own slider with the same configuration, and the values are joined with ; in row order.
• responseOther: appends an “other” choice with text input.
• keyboard: min:/max: here is what enables multiple keyboard responses; see the keyboard page.
• key: for radio/dropdown/likert/rank/checkboxes the expected answer is usually expressed as responseCode=N against the 1-based position in this column’s original order. A form slider’s responseCode is its value, or the position for a label slider.
• score: this column’s segments are the lookup keys for the score column’s values.
• required: with box responses, any value in required forces every box to be filled in before the trial can be submitted, and pressing Enter on an empty single box shows the error message and keeps the trial open (without it, that Enter is ignored). With a slider on a test trial, the Next button appears only after the first touch; in a form, an untouched required slider cannot be submitted.
• button1..button6: a slider test trial with buttons shows no Next button until the slider is touched, and a button records the slider values followed by ; and the button number. After the first touch the Next button appears too; it records the slider values only, without a button number.
• responseWindow: the waitResponseWindow and waitTimeout flags change how the response window opens and closes the trial. The minimum-duration lock is written as min: in the responseWindow column itself, not here.
• Multiplayer: responseOptions is one of the columns shared to the arena.
• Dynamic lists and variables: on form trials the expanded dynamic-list value is used, and variables in the cell are substituted before the question is built.

Examples

type	head	responseType	responseOptions	responseOptionsRandom
test	How do you feel today?	radio	Bad;Neutral;Good;None of these:exclusive	1

Randomized radio choices; responseCode records the position in the written (unrandomized) list.

type	stim1	responseType	responseOptions
test	pain_scale	slider	0(no pain)_10(worst pain);5;hideValue;removeFill

Numeric slider 0-10 with endpoint labels, starting at 5, tooltip hidden, fill bar removed.

type	head	responseType	responseOptions
form	How full is the glass?	slider	0%_100%_5;50%;hideGrid
form	How worried are you?	slider	1(Not at all worried)_2_3_4(Neutral)_5_6_7(Very worried);Neutral;hideStart

Two form sliders. The first is numeric 0 to 100 in steps of 5, starting at 50, with the endpoints shown as 0% and 100%. The second is a 7-position label slider that shows Not at all worried, 2, 3, Neutral, 5, 6, Very worried, starts hidden at Neutral and records the part as written: 1(Not at all worried), 2, 3, 4(Neutral), 5, 6 or 7(Very worried) (responseCode is the position, 1 to 7). An untouched form slider records NA.

type	stim1	stimFormat	responseType	responseOptions
test	map	.jpg	clicks	pixel;origin:center

Click response on the image reported as pixel coordinates relative to the image center. Do not add min:/max: (or any other x:y pair) to a cell that uses origin: (see Tips & gotchas); plain pixel;min:1;max:3 without origin: is fine.

type	head	responseType	responseOptions	required
form	What is your personal annual income before taxes?	box	prefix:$	1
form	What share of it would you save?	box	suffix:%	1

Two form boxes: the first shows $ before the input, the second % after it. A participant who types 50000 and 10 records 50000 and 10; the prefix and suffix are not saved.

Tips & gotchas

Caution

Flag names are case-sensitive: write waitResponseWindow, waitTimeout, noButton, removeFill and hideStart exactly as spelled. The reverse also bites: a choice text that happens to contain waitResponseWindow or waitTimeout switches that flag on by accident. Microphone flags are the exception and can be written in any case.

• Slider flags only count as a whole segment or a whole _ part: 0_100;nobutton is a plain 0 to 100 slider with a Next button, and a label such as noButton please stays a label.

Caution

Text after a number that is not a unit turns the first slider segment into a label list, not a numeric range: 1 = never_7 = always is a 2-position slider that records 1 = never or 7 = always, 1(start)_50_10(end) is a 3-position slider, and 0 percent_100 percent has 2 positions. For a numeric range, put the text in parentheses (1(never)_7(always)) or use a unit from the list under Syntax (0%_100%). The trial file editor shows a warning on such cells.

• A range that the step cannot reach is not corrected: 10_50_3 stops at 49, and 0_1_0.3 at 0.9. A start value off the step grid (0_50_10;25, -10_10;-2.5) is kept as written, so participants cannot return to it after they move the slider. The trial file editor shows a warning in both cases.
• 5_5, -5_-10 and 0_100_0 do not raise an error: the first two fall back to 0 to 100, and the third keeps 0 to 100 with step 1.
• On click trials min:/max: must be written without spaces around the colon; on keyboard trials spaces are tolerated.
• The standalone number for clicks does nothing; min:/max: is what controls how many clicks are collected.
• pixel and grid(...) cannot be combined: pixel wins.

Caution

origin: only works when it is the only x:y pair in the cell. Any other colon pair anywhere in the value (for example min:1, before or after origin:) silently cancels the origin shift, and coordinates are then reported from the default origin.

• For sliders with label lists, the recorded response is the label text, or N for a part written N(label), and responseCode is the position. Form questions and test trials record the same values.
• An untouched slider on a test trial records its start value, or NA when hideStart is present. An untouched slider inside a form always records NA, with or without hideStart, even though the handle was showing its start value. A form slider the participant deliberately sets to 0 records 0, not NA, and a required slider cannot be submitted untouched at all.
• Input attributes written in this column are only applied to input boxes, whatever the trial’s response type.
• The standalone box and comment response types split the cell on : as well as ;, so labels containing a colon behave differently there.

Common combinations

responseOptions appears in these worked recipes:

• Label choice task: Let participants assign on-screen text labels to images by drag and drop, requiring a minimum amount of labelling before they can continue.
• Likert block in random order: Present a block of likert questions in a fresh random order per participant, with the answer options in a fixed order.
• Slider rating trial: Rate each stimulus on a configurable slider scale inside an experiment trial.
• Voice-recorded picture naming: Collect spoken picture-naming responses, saving an audio recording and the voice onset for every trial.
• Factorial vignette study: Show each participant one version of a scenario from a factorial design, then have everyone rate it on the same questions.