timer

Experiments Surveys & forms Form rows without their own timer value inherit the timer of the first row on their page; a skip expiry inside a form submits the page.

Displays a countdown timer (or stopwatch) on screen during one trial or across a labeled block of trials, and can optionally auto-skip past the timed block when time runs out.

Use it for timed blocks (“you have 2 minutes for this section”), visible per-trial countdowns, hidden hard time limits (hide + skip), or an on-screen stopwatch.

Syntax

The most common form is label:options: put quiz:2m,skip on the first trial of a block, then just quiz on every other trial of the block to keep the same timer running.

The cell value takes one of four forms:

1. label:opt1,opt2,... (the value contains :): text before the colon names the timer, text after it is a comma-separated option list.
2. Letters-only value: a label reference that attaches this trial to a timer defined (with a duration) on another trial. No options are parsed in this form.
3. Digits-only value: legacy form; the number is a duration in milliseconds, and a per-trial label is generated automatically, so the timer restarts every trial.
4. Anything else without a colon: treated as an options list with an auto-generated label.

The same label on consecutive trials keeps one timer running across them; the timer only starts or resets when the label changes between trials.

Options

Each comma-separated option is trimmed and matched in this order; the first match wins:

Option	Effect
duration	30s = 30 s, 2m = 120 s, 1m30s = 90 s. A plain integer is treated as milliseconds, but only exact multiples of 1000 convert cleanly; other values are mangled (see Tips & gotchas). Prefer s/m units. Required to register a timer.
skip	When the countdown reaches 0, save a partial response tagged timeout and jump to the first trial after the timed block.
position	topleft, bottomleft, topright, bottomright, top, bottom, center (case-insensitive): where the timer is displayed. Default topRight.
stopwatch	Counts up from 0 instead of down. Still needs a duration; it stops when the elapsed time exceeds it.
hide	Timer runs but nothing is displayed. skip still fires.
danger color	A color followed by last <N>s, e.g. red last 10s: the text turns that color during the final N seconds of a countdown (or the final N seconds before a stopwatch’s limit).
size	s, m, l or xl (case-insensitive): font size s=1.5em, m=2.25em, l=3em, xl=3.75em. Default s.

Defaults & missing values

• If the column is missing or the cell is left blank, the trial has no timer. Entering a timer-less trial after a timed one stops and clears the running timer.
• Exception for type=form rows with an empty timer cell: the row inherits the timer of the first row of its form page (the row after a pageBreak=1), so one timer covers a whole form page.
• Option defaults: countdown (not stopwatch), shown top right, size s, visible, no skip, no danger color.
• A timer is registered under its label only the first time a value with a duration is seen; later definitions of the same label are ignored.
• The countdown displays mm:ss when minutes remain, otherwise just seconds, never below 00, refreshed about every half second.
• The cell value is echoed into the results file like every recognized column.

Works with

• random / randomBlock: timer labels bound the shuffle groups. A randomization group closes wherever the timer label changes between adjacent rows, so randomization never moves a trial out of its timed block.
• randomPick / trialGroup: with trialGroup defined, the timer label is part of each pick pool’s identity, so picking respects timed blocks; without trialGroup it is not. After picking, the within-block shuffle sees the timer labels in the final trial order, so its block boundaries stay aligned with the timed blocks.
• trialOrder sampling specs (N: sample ...): sampling pools split wherever the timer label changes, so trials from different timed blocks are never pooled together, and a pool’s error message names the timer.
• type=form: label inheritance across a form page (see above); when a skip timer expires inside a form, the form is completed and the participant jumps past the timed block.
• responseType=mic: on skip expiry, mic trials finish through their own recording flow instead of ending immediately.
• then column timer:start: unrelated to this column. That value controls when time-based break countdowns begin.
• presTime: independent. presTime limits stimulus presentation inside a trial; timer overlays a clock and (with skip) can end the whole block.

Examples

Legacy per-trial 30-second countdown (milliseconds form; auto-label, restarts every trial):

type	stim	presTime	timer
test	face1	5000	30000
test	face2	5000	30000

Labeled 2-minute block timer with auto-skip and red warning, shared across trials (defined on the first trial, referenced by label on the rest):

type	stim	timer
instruction	You have 2 minutes
test	item1	quiz:2m,skip,topLeft,red last 10s
test	item2	quiz
test	item3	quiz
instruction	Section done

When the 2 minutes expire while any quiz trial is on screen, the participant jumps to the “Section done” trial (the first trial after the last quiz-labeled trial).

Real files write this same block pattern with a single-letter label (the form the editor accepts): define the timer once, then reference it with the bare label: form on each following trial:

type	stim	timer
test	item1	A:90s,l,skip,red last 10s
test	item2	A:
test	item3	A:

Hidden hard limit and a visible stopwatch:

type	stim	timer
test	speeded_task	limit:45s,skip,hide
test	drawing_task	watch:90s,stopwatch,center,l

Tips & gotchas

Caution

Write durations with explicit s/m units. In the legacy digits-only form the number is divided by 1000, so 30 means 0.03 s. Inside an options list only exact multiples of 1000 convert cleanly (30000 = 30 s); other values are mangled (30 becomes 3 s, 500 becomes 5 s, 45500 becomes 5 s).

• A colon-less value starting with letters is always a label reference, and only the leading letters are kept: timer1 becomes label timer, which will not match a timer defined as timer1:60s (whose label is the full timer1). Keep labels letters-only.
• Consequently stopwatch or skip alone (no colon, no duration) is read as a label reference, not as options. Options-only values must carry a duration or use the label:options form.
• A label that is referenced but never defined with a duration breaks the experiment during setup; every referenced label needs one definition with a duration.
• The first definition of a label wins; a later trial redefining the same label with different options or duration is silently ignored.
• Re-entering a label after leaving it restarts the timer from 0, but skip always jumps past the last block using that label in the run order, so a skip from an earlier block jumps over everything up to there.
• In the danger-color option, hex colors containing the digits 7 to 9 are not recognized (#ff7700 last 10s is ignored); named CSS colors always work.
• An option that repeats a token already matched by an earlier option in the same list can occasionally fail to be recognized; keep option lists simple and distinct.
• skip only fires while a trial carrying the timer’s label is on screen, and expiry is checked about every half second.
• Timers are stopped and cleared at experiment end.

Common combinations

timer appears in these worked recipes:

• Timed block with skip: Run a block of trials against one shared countdown that ends the whole block when time runs out.
• Visible countdown per trial: Show a countdown that restarts on every trial, with the deadline itself enforced by the response window.