keyboard

Experiments

Defines which physical keyboard keys are valid responses for a trial. When keyboard is filled in, the trial’s response is collected from the keyboard: a matching key press records that key’s name as the response and ends the trial. Setting keyboard also switches the trial away from the default response mode (typing an answer or clicking the stimulus) to key presses instead, unless responseType is one of slider, box, comment. On instruction-type screens, filling in keyboard lets participants advance with a key press and hides the NEXT button that would otherwise appear.

Syntax

Put the key you want to accept in the cell, for example space. To offer a choice between keys, list them separated by spaces: left right, f j, y n.

Values are case-insensitive, and any run of characters that is not a letter, a digit or + acts as a separator, so a b, a,b, a;b and a&b are all the same list.

The keys you can name:

• Single letters and digits: a to z, 0 to 9. Digits also accept the matching numpad key.
• Named keys: space, enter, escape, and the arrows left, right, up, down.
• Modifiers as response keys: shift, ctrl, alt, optionally restricted to one side by gluing it on: shiftleft, shiftright, ctrlleft, ctrlright, altleft, altright.
• Combinations: a modifier (optionally sided) plus + plus one ordinary key, for example alt+a, ctrl+space, altleft+b. Only the modifier can be restricted to a side. Spaces around the + are ignored, so alt + a also works.
• all: accepts any letter, digit or named key. Modifier keys are deliberately not included in all.

How presses are matched:

• A plain key only counts when no modifier is held, so a, alt+a and ctrl+a are three different responses.
• A combination needs its modifier held down, on the required side if you specified one.
• A modifier listed on its own counts as soon as it is pressed, whatever else is held. This is deliberate, so that AltGr layouts still work.

The response recorded in the results is the token that matched, for example a, space, alt, altright or alt+a.

Options

Value / token	Meaning
empty cell	No keyboard responses (default; but see Tips & gotchas)
a … z	Single letter key (case-insensitive)
0 … 9	Digit key, top row or numpad
space, enter, escape	Named special keys
left, right, up, down	Arrow keys
shift, ctrl, alt	Modifier key as a response key
shiftleft/right, ctrlleft/right, altleft/right	Side-specific modifier as response key
<mod>+<key> e.g. alt+a, ctrlright+2	Combination: modifier held while key pressed
all (anywhere in the value)	Any letter, digit or named key is a valid response; the response is the key’s name
multiple tokens separated by any non-alphanumeric characters	List of alternatives, e.g. a,l / a l / a;l

Defaults & missing values

Leave the column out of the trial file, or leave a cell empty, and that trial accepts no keyboard responses at all: key presses are ignored and cannot end the trial.

A trial counts as a keyboard trial as soon as its keyboard cell has any value.

On test and practice trials with keyboard empty and no button1, clicking the stimulus becomes the response instead.

Works with

• responseType: keyboard responses are ignored when responseType is slider, box or comment. Other response types (for example label or clicks) work alongside keyboard keys.
• responseType mic: keys stay active during a microphone recording, but a press does not cut the recording short. The recording is finished first, then the key you pressed is stored as the trial’s response with the audio intact.
• responseOptions min:N / max:N: lets the participant press several keys in one trial. The pressed keys are recorded joined with ;, a Confirm button appears once min presses have been made, and the trial ends automatically at max. The reaction time of each individual press goes to the RTkeys results column.
• key: the recorded key token (for example a) is compared against the key column to score the trial as correct or incorrect.
• responseWindow with a min: duration: while the minimum window is still open, the participant’s last key press is held back and only submitted when the window closes.
• Instructions screens: filling in keyboard lets participants advance with a key press, and with presTime set to 0 it also hides the default NEXT button.
• ALT keys: as soon as any token uses alt, the browser’s own ALT behavior (menu focus, shortcuts) is suppressed for the trial.
• Multiplayer chat: key responses are suspended while a chat is in progress, so typing a message cannot end a trial.

Examples

type	stim1	keyboard	key	presTime
test	word_old	a l	a	2000

Two-alternative response: press A or L; A is correct.

type	stim1	keyboard	responseOptions
test	recall_prompt	all	min:3;max:5

Any letter/digit/named key accepted; participant must press at least 3 keys, at most 5; responses recorded as k1;k2;k3.

type	stim1	keyboard
test	bilateral_task	altleft altright

Left ALT vs right ALT as the two response keys; response recorded as altleft or altright.

Most real trials use the simplest forms these examples generalize. A single key, or space-separated single keys:

type	stim1	keyboard	key
test	go_signal	space	space
test	pair	left right	left

space alone, and space-separated pairs like left right / y n / f j, are the dominant real patterns.

Tips & gotchas

Caution

Any value that merely contains the letters all, such as the typo ball, silently turns on any-key mode on top of the keys the rest of the value describes.

• There is no any keyword. Writing any gives you the three separate keys a, n and y.
• Names that are not recognized fall apart into single letters: arrowleft becomes the keys a, r, o and w plus left. Use left, right, up and down for the arrow keys.
• A plain key does not match while a modifier is held, so with keyboard set to a, pressing SHIFT+A registers nothing.
• A modifier listed on its own matches even when another modifier is held. This is intentional, because AltGr is reported as CTRL+ALT.
• For sided combinations, the side that counts is the side of the modifier the participant is actually holding.

Note

Holding a key down cannot produce extra responses: auto-repeat is ignored until the key is released. With responseOptions min:/max:, every recorded key therefore needs its own fresh press.

Common combinations

keyboard appears in these worked recipes:

• Replayed random order: Shuffle a block once, then replay that exact order in a later block so both passes share identical order effects.
• Adaptive staircase: Home in on a participant’s detection threshold by making trials harder after correct answers and easier after misses.
• Between-subject conditions: Give each participant one of two stimulus sets, while shared screens run for everyone.
• Go/no-go task: Score a press as correct on go trials and a withheld response as correct on no-go trials.
• Nested block shuffle: Randomise the order of whole task sections and of the mini-blocks inside each section, keeping every block’s trials together.