buttonN

Experiments Surveys & forms On experiment trials the buttons are the response choices; on forms and surveys button1 instead renames the submit button.

button1..buttonN define the labels of on-screen clickable response buttons for a trial. Any non-empty value in a button column makes that button part of the trial’s response set; the participant clicks a button to respond, and the recorded response is the button’s number (not its label). Buttons are the click-based alternative to keyboard responses, and they double as the submit/advance button on instruction trials, forms/surveys, text-input trials, slider trials, sort trials, and multi-click selection trials.

The number of available button columns is not fixed at 6: up to 12 buttons (button1..button12) are supported, and how many columns your file offers grows with the file itself, capped at 12.

Syntax

Put the button’s label in the cell, e.g. button1: Yes, button2: No; leave a cell empty for no button.

• One column per button: button1 is the leftmost, buttonN the rightmost; all buttons of a trial are laid out on one horizontal row centered on the screen.
• Labels are free text and are rendered as HTML, so markup like <br> works.
• Column names are case-insensitive like all columns.
• No sub-syntax is parsed: the cell content is not split, variables are not substituted, and there are no special prefixes.

Options

Value	Effect
empty cell	Button does not exist for this trial. If button1 is empty, the entire button response mode is off for the trial.
any other text	Rendered as the button’s HTML label. The recorded response is still the button number.
text containing HTML	Markup renders.

The number of buttons shown on a trial equals the highest defined button index, regardless of gaps.

Defaults & missing values

• When a button column is absent or its cell is left empty, that button does not exist; with button1 empty, no response buttons are shown at all.
• There is no default label for response buttons; the label always comes from the cell.
• On instruction-type trials with button1 empty and no keyboard or presTime set, a single advance button still appears with the default label for the experiment’s language (NEXT in English). Filling button1 replaces that label.
• On form/survey trials, button1 overrides the submit button caption; otherwise NEXT or FINISH is chosen based on whether the next trial is also a form.

Works with

• Response gating: buttons are active on a trial only when button1 is filled; they appear once responses are enabled.
• keyboard: buttons and keyboard can coexist; both are enabled in the same trial. Clicking directly on stimuli is auto-enabled only when both keyboard and button1 are empty on test/practice trials; word stimuli additionally require responseType to be empty or clicks.
• key (scoring): the click records the button number as the response (1..12). A response matching key is scored correct (1), a non-match incorrect (0), and a trial with key empty is left unscored. So to mark button 2 as correct, put 2 in key.
• responseType: box|comment|slider: when a text box or slider is visible, the button acts as submit and the recorded response becomes <inputValue>;<buttonNumber>. With required set and an empty response box, the click is ignored. The buttons row is pushed below the visible input.
• responseType: clicks: button1 becomes the confirm button for a stimulus click selection; the recorded response is the clicked stimulus index. button1 stays hidden until a stimulus is clicked.
• Clickable stimuli active alongside buttons: the response is <clickedStim>;<buttonNumber>.
• Sort trials: with button1 set, it replaces the default submit button on sort and response-label trials.
• responseType: mic: while the mic is still recording, a button click does not end the trial immediately: the recording is finalized first, then the trial is saved with the button number as the response.
• responseWindow: on timeout, the response is recorded as 999 and marked as a timeout.
• test: CFPT: button1 finalizes the CFPT sort instead of recording a numeric response.
• Results: besides the numeric response, the clicked button’s visible text is saved in the results.
• Layout: buttons get narrower as their count grows (one button is widest, twelve narrowest), all buttons in the row share the same height, and on mobile instruction screens button1 moves below the content. On drag trials with a background, the save button borrows button1’s styling but always shows the default NEXT label, and appears only when button1 is not active for the trial.

Examples

Two-alternative forced choice, “old” is correct (response recorded as 1 or 2; key: 1 scores button 1 correct):

type	stim1	stimFormat	button1	button2	key
test	face01	.jpg	old	new	1

Six-point rating with no correct answer (left unscored):

type	stim1	stimFormat	button1	button2	button3	button4	button5	button6
test	statement1	word	1<br>never	2	3	4	5	6<br>always

Instruction trial with a custom advance label (records response 1 when clicked):

type	content	button1
instructions	Welcome to the study	Start

Tips & gotchas

Caution

button1 is the master switch: if it is empty while button2 and up are filled, no buttons are shown at all. Always fill buttons starting from button1 without gaps.

• Gaps render as junk buttons. A trial with button1 and button3 filled but button2 empty still displays three buttons, and the middle one shows a meaningless placeholder label. Keep the filled columns consecutive.
• Labels are raw HTML with no variable replacement, unlike title/content where variables are substituted.
• Response = position, not label. Swapping label texts between columns changes what participants see but not the recorded numbers; only the saved response text reflects the label.
• Cap at 12. Even when the trial file nominally offers more button columns, only button1..button12 can display; button13 and up never show.
• First-trial zoom reset: a button1 click on the very first trial also resets the browser zoom to 100%.

Common combinations

buttonN appears in these worked recipes:

• Ambient audio across trials: Start a looping background track on one trial and cut it at a later trial, leaving the rest of the block silent.
• Trials from a stimulus list: Expand a single trial-file row into one trial per item of an uploaded stimulus list, in a fresh random order each session.
• Video then buttons: Play a video clip and only reveal the response buttons once playback has finished.
• End-of-block summary: Show participants their accuracy and average response time on a summary screen after a block of scored trials.