Skip to main content
V2 data forms can declare keyboard shortcuts as a top-level array on the schema. Each entry binds a key combination to a named script and is registered under a per-form scope, so a form effectively resets all of its shortcuts every time it mounts — you never have to manually un-register them.

​
Why declarative

Shortcuts live in the schema next to scripts and bridge. The form author writes a key → script mapping; the platform handles registration, scoping, and cleanup. Because each shortcut points at a named script, the same script can be invoked via a hotkey, a button click, a trigger, or a service-bridge response without duplicating code.

​
Schema

Add a shortcuts array to the form’s top-level definition: 
version: "2"
bridge:
  permissions: ["data:read", "navigation"]
shortcuts:
  - key: "control+1"
    description: "Jump to the invoice page"
    group: "navigation"
    scriptRef: gotoInvoice
  - key: "control+f"
    altKey: "meta+f"
    description: "Focus the total field"
    scriptRef: focusTotal
scripts:
  gotoInvoice: |
    (ctx, bridge) => bridge.navigation.setPage(1)
  focusTotal: |
    (ctx, bridge) => bridge.navigation.focusAttribute(
      ctx.dataObjects[0]?.uuid,
      "invoice/total"
    )
nodes:
  - component: v2:panel
    # ...

​
FormShortcut Fields

FieldTypeRequiredDescription
keystringYesPrimary binding (e.g. "control+1", "meta+shift+s")
altKeystring | string[]NoOne or more alternative bindings that also fire the script
descriptionstringYesLabel shown in the keyboard-shortcuts help dialog (⌘/)
groupstringNoHelp-dialog group: "navigation", "zoom", "data-entry", "document", or "ui"
scriptRefstringYesName of a script in the form’s scripts map to invoke

​
Lifecycle and scoping

Every shortcut is registered under the scope form:<viewId>. The platform:
  1. On mount — clears the scope (so a stale registration from a previous mount is gone), then registers each entry under the scope.
  2. On shortcuts change — runs the same clear-then-register cycle automatically. Hot-reloading a form during development replaces the bindings cleanly.
  3. On unmount — clears the scope. Shortcuts from other forms or the global help dialog are untouched.
Because scopes are isolated, two open forms can register the same key in different ways — the binding effective at any moment is the one belonging to the most recently mounted form for that key.
If your form’s key collides with a global shortcut already in the help dialog (for example meta+/), the existing global binding wins and the form’s is silently dropped. Prefer keys not used globally.

​
Cross-platform notation

You author bindings with the same key string on every platform (for example control+1), and the platform normalizes them to the keystroke each browser actually delivers, so most bindings work for Windows, Linux, and Mac reviewers without per-platform entries. On Mac this means:
  • control+X is rewritten to ⌘⌥X (meta+alt) at runtime. A binding declared as control+1 therefore fires when a Mac reviewer presses ⌘⌥1, not the physical Control key. This is expected — if you are debugging why a control+1 shortcut appears to respond to ⌘⌥1 on Mac, that is the normalization at work.
  • alt+<letter> and alt+<digit> chords auto-derive the macOS-substituted character. macOS turns ⌥+key into a special character (for example ⌥R→®, ⌥6→§, ⌥⇧R→‰), and the shortcut auto-registers that form so a plain ⌥+key still triggers. Note: the option dead-key letters (e, i, n, u) and ⌥⇧K produce no standalone character and are not auto-derived — declare an explicit altKey for those.
  • Registered chords are reclaimed from the browser. Any registered chord is intercepted in the capture phase (preventDefault) so the browser’s built-in behaviour — Chrome tab switching on Ctrl+PageDown / Ctrl+5–8 (matched as ⌘⌥5–8 on Mac), for example — doesn’t consume it first. This only applies when focus is outside an input, textarea, select, or contentEditable element, so typing in a field is never affected.
The altKey field still lets you add explicit alternative bindings when you want one; the Mac rewrites above happen automatically and do not require an altKey entry.

​
Inside the script

Scripts referenced by scriptRef follow the standard V2 signature — a function of (ctx, bridge): 
(ctx, bridge) => {
  // ctx exposes the form's data context plus a `shortcut` payload
  // describing the FormShortcut entry that fired this invocation.
  bridge.log.debug("Triggered by " + ctx.shortcut.key);

  // bridge.* gives you the same Bridge API documented under
  // "Bridge API & External Services".
  bridge.navigation.setPage(1);
}
The ctx.shortcut payload ({ key, description, scriptRef, ... }) is added by the shortcut dispatcher so a single script can branch on which binding fired it.

​
What scripts typically do

The most common actions a shortcut performs are spatial navigation, attribute focus, and data-object manipulation — all available through the bridge: 
// Jump the spatial viewer to a known page
bridge.navigation.setPage(3);

// Focus a specific field and highlight its tag in the document
bridge.navigation.focusAttribute(parentUuid, "shipment/originZip");

// Read the current page so a shortcut can "go to next page in this group"
const current = bridge.navigation.getCurrentPage();
const total = bridge.navigation.getPageCount();
if (current && current < total) bridge.navigation.setPage(current + 1);

// Add a child data object under a known parent
const obj = await bridge.data.addDataObject(parentUuid, "LineItem");
bridge.data.setAttribute(obj.uuid, "LineItem/Description", "New line");
See Bridge API & External Services for the full method surface.

​
Example: rotate the current page

A common review task is fixing a sideways scan. bridge.navigation.rotatePage(direction) rotates the spatial viewer’s current page by 90° in the given direction, and a pair of shortcuts makes it a one-keystroke flip: 
version: "2"
bridge:
  permissions: ["navigation"]
shortcuts:
  - key: "alt+r"
    description: "Rotate page right"
    group: "document"
    scriptRef: rotateRight
  - key: "alt+shift+r"
    description: "Rotate page left"
    group: "document"
    scriptRef: rotateLeft
scripts:
  rotateRight: |
    (ctx, bridge) => bridge.navigation.rotatePage("right")
  rotateLeft: |
    (ctx, bridge) => bridge.navigation.rotatePage("left")
alt+r and alt+shift+r are example bindings chosen by the form author — exactly like every other shortcut in this guide, you pick the keys — not a fixed global hotkey. Swap them for any combination that suits your reviewers. A few things to know about rotatePage:
  • Permission. It calls the navigation capability, so "navigation" must be in bridge.permissions.
  • Direction is "left" or "right". Those are the only two accepted values. Any other string is ignored (a console warning is logged and the call is a no-op).
  • Rotation is relative. Each call turns the page ±90° from its current angle rather than setting an absolute angle — so calling rotatePage("right") twice lands at 180°, and a following rotatePage("left") returns it to 90°.
  • Current page only. It rotates just the page the viewer is on. Rotating every page of a document remains a separate menu action.
  • Targets one document. With no argument it rotates the page of the form’s default (first) document family. Pass an optional documentFamilyId — bridge.navigation.rotatePage("right", familyId) — to target a specific open document; rotation applied to one document does not bleed across to others.
The method returns nothing. An invalid direction logs a console warning and is a no-op, but a missing navigation permission throws a Permission denied: navigation error like any other gated Bridge call.

​
Permissions

Shortcut scripts call the same Bridge API as any other V2 script, so they obey the same bridge.permissions contract. A shortcut that calls bridge.navigation.setPage(...) needs "navigation" in the form’s permissions array; one that calls bridge.data.addDataObject(...) needs "data:write". Permission errors surface to the browser console and the shortcut becomes a no-op.

​
Help dialog

Registered shortcuts appear in the global keyboard-shortcuts help dialog (open with ⌘/ on Mac or Ctrl+/ on Windows/Linux), grouped by the optional group field. Use a clear description — that’s what users will see when they’re hunting for a key.

​
Example: invoice review form

A reviewer-oriented form that binds the number keys to the document’s classification groups and uses Tab-like flow to move between common fields: 
version: "2"
bridge:
  permissions: ["data:read", "data:write", "navigation"]
shortcuts:
  - key: "control+1"
    description: "Jump to Invoice"
    group: "navigation"
    scriptRef: gotoInvoice
  - key: "control+2"
    description: "Jump to Bill of Lading"
    group: "navigation"
    scriptRef: gotoBOL
  - key: "control+t"
    description: "Focus invoice total"
    group: "data-entry"
    scriptRef: focusTotal
  - key: "control+n"
    description: "Add a line item"
    group: "data-entry"
    scriptRef: addLineItem
scripts:
  gotoInvoice: |
    (ctx, bridge) => bridge.navigation.setPage(
      ctx.invoicePage ?? 1
    )
  gotoBOL: |
    (ctx, bridge) => bridge.navigation.setPage(
      ctx.bolPage ?? 2
    )
  focusTotal: |
    (ctx, bridge) => bridge.navigation.focusAttribute(
      ctx.dataObjects[0]?.uuid,
      "invoice/total"
    )
  addLineItem: |
    async (ctx, bridge) => {
      const parent = ctx.dataObjects[0];
      const obj = await bridge.data.addDataObject(parent.uuid, "LineItem");
      bridge.navigation.focusAttribute(obj.uuid, "LineItem/Description");
    }
When the reviewer opens this form, four shortcuts appear in the help dialog under “Navigation” and “Data Entry”. Switching to a different form removes them; reopening this form restores them. No manual cleanup is required.

​
Conformance

The shortcut dispatcher and Bridge API are covered by a conformance suite in kodexa-ui/src/schema/runtime/conformance/. Each binding behaviour ships as a paired .js + .expected.json script that runs against a stub-store-backed Bridge — the suite catches binding regressions before they reach the browser.