Configure project shortcuts

A shortcut is a key or key combination, also called a chord. A config can attach shortcuts to fields and to individual choices. Both appear automatically in the app’s ? dialog, so labelers can find the current bindings there.

Try a form that uses built-in number keys →

Syntax

[modifier+]…key

Modifiers: mod, ctrl, alt, shift, meta. cmd and opt work too, for anyone reading them off a Mac keycap — they mean meta and alt.

mod is ⌘ on macOS and Ctrl everywhere else — write mod and both platforms are correct.

The key is a single letter or digit, or one of the named keys:

space enter escape tab left right up down home end backspace delete

"shortcut": "p"           // bare letter
"shortcut": "3"           // digit
"shortcut": "mod+s"       // ⌘S / Ctrl+S
"shortcut": "mod+shift+k" // ⌘⇧K / Ctrl+Shift+K
"shortcut": "mod+up"      // a named key

Punctuation is deliberately not offered. The app owns ? and mod+,, and leaving punctuation out of the config grammar means no config can claim them.

Two places to attach one

On a field — moves focus to its widget:

{ "name": "notes", "type": "text", "widget": "textarea", "shortcut": "mod+n" }

Worth it for a field a labeler has to type into, which is otherwise several Tabs away. A field with choices rarely needs one: the choice chords below reach the answer without focusing anything. Fields that do not declare a shortcut are not listed in Settings as unbound focus actions — a row per field for something Tab already does buries the chords that matter.

On a choice — selects it directly, without focusing anything first:

{
  "name": "verdict",
  "type": "enum",
  "choices": [
    { "name": "correct", "display": "Correct", "shortcut": "c" },
    { "name": "incorrect", "display": "Incorrect", "shortcut": "x" },
  ],
}

Choice chords work on multi-selects too, where they toggle rather than replace.

One namespace for the whole config

Field chords and choice chords share a single namespace. Two fields, two choices, or a field and a choice claiming the same chord is an error:

Shortcut "c" is already used by choice "correct" on "verdict".

This is because choice chords fire app-wide, not only while their own field has focus. That is what makes them worth having — you press c without tabbing anywhere first. It also means two fields claiming c would be a genuine ambiguity with no way to resolve it.

Reserved chords

A config may not claim a chord the app or the OS already owns:

Chord	Owned by
`mod+z` `mod+x` `mod+c` `mod+v` `mod+a`	Undo / Cut / Copy / Paste / Select All
`mod+q` `mod+w` `mod+m` `mod+h`	Quit / Close / Minimise / Hide
`mod+r`	Reload
`mod+enter`	Save & export
`mod+shift+l`	Switch to Label mode
`mod+shift+p`	Switch to Prepare mode
`mod+,`	Settings
`enter` `space`	Next record
`left` `right` `shift+left` `shift+right`	Moving through records

Claiming one is a config error rather than a silent override. The renderer calls preventDefault on a match, so mod+v in a config would stop Paste working in the notes box with nothing on screen to explain why.

A bare letter that merely appears inside a reserved chord is fine — "c" is unrelated to mod+c. Adding a modifier makes a different chord, so shift+left being reserved does not reserve mod+shift+left.

Reserved-ness is about the keystroke rather than the spelling. cmd+v and ctrl+v are each Paste on one platform, so reserving mod+v covers both.

Derived fields cannot take one

A copy or timestamp field renders no widget, so there is nothing to focus:

{ "name": "id", "type": "text", "fill": { "kind": "copy" }, "shortcut": "i" }
// ✗ A "copy" field renders no widget, so there is nothing to focus.

Budgeting shortcuts

The built-in 1–9 already picks the nth choice of the focused choice field, and costs nothing to declare. Start there. For a form whose main question is a three-way rating, digits plus Enter is the entire interaction.

Declare explicit chords when:

Two choice fields compete for the digits. Give the secondary one mnemonic letters.
The letters are easier to remember. c/x for correct/incorrect beats 1/2 because it survives someone reordering the choices.
A field is far down a long form. A field chord jumps straight to it.

Prefer bare letters for choices (fast, and the digits stay free) and mod+ chords for fields (they keep working from inside a text box — see below).

Why a bare letter sometimes does nothing

Bare chords are suppressed while the labeler is typing: in an input, a textarea, or a dropdown’s search field. Otherwise a chord on c would make the letter “c” impossible to type into the notes box.

Ctrl, Cmd, and Alt combinations remain eligible while typing. Bare and Shift-only shortcuts are suppressed in text-entry controls. An open dialog owns the keyboard.

Radio groups and sliders are a deliberate middle ground: they consume arrow keys, not letters, so bare choice chords keep working while one of them has focus. That is what makes those chords usable from anywhere on the form.

Full reference

OutputField · Choice · the labeler’s view