Responses define the actions that participants can take in response to stimuli. They also implicitly specify what types of participant data will be recorded in a study.

A response is defined by a key-value pair inside the top-level property responses in a study runtime specification. Similar to a stimulus, the key of a response definition serves as the name of the response, which can be referenced in other parts of the specification. Its value specifies the type of the response, and its relevant properties.

For example, the following snippet

"response1": {
  "type": "choice",
  "choices": ["Correct", "Wrong"],
  "key_mapping": ["F", "J"],
  "target": "Correct", // or equivalently "target": ["Correct"]
  "feedback": false

defines a response of type choice, with two options labeled as “Correct” and “Wrong”. Each option will be rendered as a clickable button, and can also be triggered by pressing the F or J key respectively. Finally, the correct answer to this choice response is “Correct”, but no feedback will be given regardless of the participant’s choice.

Common properties

All responses share the following common properties:

  • type - must be specified as one of the types described below

  • parent (optional) - the name of another response; if specified, then the properties of the other response will be inherited by this response, unless a property of the same name is defined in this response.

  • delay (optional) - delay the displaying of a response, relative to the latest onset of all stimuli on a given trial, by a certain number of seconds (fractions are supported). Default (or omission) is 0. This setting can be useful for forcing participants to read some text before making a response.


    The latest onset of all stimuli on a given trial is the moment when all stimuli just become visible (or start playing).

Visible responses

Visible responses can be seen by participants. They are usually used to explicitly elicit a response from participants.

All visible responses share the following common property:

  • instruction - (optional, with an intuitive default instruction assigned to most response types) a short text providing the necessary instructions for participants about the current response

A choice response allows participants to choose between several alternatives.

  • type - must be specified as choice
  • choices - a list of options in the form of ["option1", "option2", ...] representing the alternative options. Note that (1) if each option is a plain text label, these options will be rendered as buttons during a study so that participants can click on one of them; (2) if a special format "%s:name-of-stimulus" is used, FindingFive will use the corresponding stimulus defined in the study. A clickable image will be rendered if the stimulus being referenced is an image stimulus. A clickable video will be rendered if the stimulus is a video stimulus. A clickable text box will be rendered if the stimulus is a text stimulus; (3) mixing text label options and stimulus references works as well, but sometimes it doesn’t make sense (e.g., mixing labels and videos).
  • target (optional) - a single correct answer, or a list of correct answers (as in ["correct", "also correct"]). All target values must already be listed in choices. When target is a list, participants’ choices must match exactly all listed targets. In the case of stimulus references, the target should be listed as "%s:name-of-stimulus".
  • sample_k (optional) - instead of presenting all options defined in choices, sample k out of them randomly. If a target is defined, those options will always be presented, and an additional k - the number of targets options will be drawn from the remaining “distractors”. If left undefined, the default value is the total number of options as defined in choices.
  • key_mapping (optional) - a list of single-character individual key names (e.g., ["F", "J", ...]), each specifying which key can be pressed to choose the option presented. Note, the length of this list must be the same as sample_k, and the correspondence between options and keys are location-aligned (this means that keys are not tied to the values of options but the locations they are presented at).
  • key_only (optional) - if key_mapping is defined, setting this property to true will allow participants to respond with key presses only. Note this currently only works for text labels rendered as buttons.
  • locations (optional) - either "fixed" (default) or "random", changing whether the locations of the choices are randomly determined on a trial
  • feedback (optional, boolean) - if a target is specified, whether or not participants will receive feedback (both visual and auditory feedback is presented). Defaults to false (i.e., no feedback even if a target is specified)
  • multi_select (optional) - if true (default is false), participants are allowed to select one or more options as defined in "choices". A confirm button will be available to lock in the response. Note: this option currently only works plain text labels, which are rendered as buttons.
  • incremental_feedback (optional, boolean) - if multi_select is true and target is an array, whether or not participants will receive immediate feedback after each choice they make. This can be turned on or off independently of feedback. For example, if feedback is true and incremental_feedback is false, then participants will only receive feedback after they confirm their selection.
  • ordered (optional, boolean), - if multi_select is true, whether or not the order in which targets are listed in target matters. When this is set to true, participant response is still considered incorrect even when the correct set of options are selected, but in an incorrect order.
  • layout (optional) - either "horizontal" (default) or "vertical", changing how the choices are displayed on a trial
Recorded data:
  • value - the choice made by the participant
  • correct - whether the choice(s) made by the participant matches target
  • rt - reaction time, defined as the number of milliseconds between the start of the presentation of the buttons and the moment when the participant makes a choice
  • mode - whether the participant responded via a key press or a mouse click

A rating response allows participants to express their opinion using a numeric scale.

  • type - must be specified as rating
  • upper_bound (optional) - the number of steps on the scale; default is 5. See the next property zero_centered for details.
  • zero_centered (optional) - if set to true, the rating scale will be centered on 0, ranging from -upper_bound to +upper_bound. Default (or omission) is false, where the rating scale will range from 1 to upperbound.
Recorded data:
  • value - the rating selected by the participant
  • rt - reaction time, defined as the number of milliseconds between the start of the presentation of the scale and the moment when the participant responds

A text response allows participants to answer a question or leave a comment by typing in a text box.

  • type - must be specified as text
  • required (boolean, optional, default false) - whether participants must provide a response
  • max_char (optional) - the maximum number of characters allowed in this response.
  • target (optional) - the expected correct response, if any. All leading and trailing whitespaces in the participant’s response will be removed before being compared to the target.
  • target_match (boolean, optional, default false) - if set to true, participants must type in an answer that matches the target as defined above in order to continue the study (a good use case of this feature is to implement a passcdode).
  • width (optional) - the width of the text box, preferrably in “px” (pixels).
  • height (optional) - the height of the text box, preferrably in “px” (pixels).
Recorded data:
  • value - the text typed in by the participant

An audio response allows participants to record their answer (this feature works most reliably in Chrome and Firefox).

  • type - must be specified as audio
  • padding - (optional, default at 500) the number of milliseconds it will continue to record after participants hit stop. Default is 500. This parameter prevents participants from cutting off their recording too quickly (i.e., hitting stop while still speaking).
Recorded data:
  • a sound file, which will be saved and included in the downloadable zip archive containing your participant data. The name of the sound file will appear in the value field in the downloadable CSV.

Background responses

Background responses are invisible to participants. They are most commonly used to record participant behavior during a trial covertly, or in conjunction with a visible response.


A keypress response records all keys that a participant presses during a trial.

  • type - must be specified as keypress
  • multiple (boolean, optional, default true) - if true, then record all key presses during a trial; if false, only the first key press will be recorded.
  • whitelist (list of characters, optional) - a list of characters, such as ["d", " ", "k"], to indicate which keys FindingFive should monitor. Key presses outside the whitelist are ignored and not recorded.
  • blacklist (list of characters, optional) - a list of characters to indicate which keys FindingFive should not monitor. Key presses outside the blacklist are recorded.
Recorded data:
  • value - the name of the key pressed by the participant
  • rt - the duration in milliseconds between the last key press and the current one; for the first key press, rt is the duration between the activation of this response and the first key press.