Hotkeys

📖 Table of Contents

Overview
Defining a Hotkey
Hotkey Reveal (Ctrl Discovery)
Context Sensitivity
Conflict Resolution
Accessibility Considerations
Further Examples

Overview

SmarkForm supports keyboard shortcuts (hotkeys) for trigger components. Hotkeys let users activate any trigger — addItem, removeItem, export, clear, or any custom action — without reaching for the mouse.

Hotkeys are:

Opt-in — only triggers that declare a hotkey option participate.
Context-sensitive — the same key can mean different things depending on which component currently has keyboard focus.
Discoverable — pressing and holding Ctrl reveals all active hotkeys as visual hints on their trigger buttons.

Defining a Hotkey

Add the hotkey property to a trigger’s data-smark object:

<!-- Add a new list item with Ctrl+Plus -->
<button data-smark='{"action":"addItem","context":"phones","hotkey":"+"}'>
    ➕ Add Phone
</button>

<!-- Remove the current item with Ctrl+Minus -->
<button data-smark='{"action":"removeItem","hotkey":"-"}'>
    ➖ Remove
</button>

The value of hotkey must match the browser’s KeyboardEvent.key string for the desired key (e.g. "+", "-", "s", "Enter", …). Single printable characters are the most portable and least likely to conflict with browser or OS shortcuts.

Hotkey Reveal (Ctrl Discovery)

When the user presses and holds Ctrl, SmarkForm:

Finds all trigger components that have a hotkey option and whose context is an ancestor (or sibling ancestor) of the currently focused element.
Sets the data-hotkey attribute on each matching trigger button to the configured key character.

Your CSS can use this attribute to show a visual hint. SmarkForm’s bundled sample CSS shows a small floating badge — you can style it any way you like:

/* Example: show hotkey badge on the button */
[data-hotkey]::after {
    content: "Ctrl+" attr(data-hotkey);
    position: absolute;
    /* … your positioning and style … */
}

When Ctrl is released, the data-hotkey attributes are removed and the hints disappear.

Pressing a key while Ctrl is held activates the matching trigger (if one was revealed).

Holding Ctrl+Alt reveals a second level of hotkeys. This is useful when the same key is used for multiple actions at different nesting levels — pressing Ctrl shows the innermost one, Ctrl+Alt shows an outer one.

Context Sensitivity

Hotkeys are scoped to the focus context. The same key binding can be re-used in different parts of the form without conflict:

🔗

🗒️ HTML

🎨 CSS

⚙️ JS

👁️ Preview

❓

<div id="myForm">
  <ul data-smark='{"type":"list","name":"users"}'>
    <li>
      <input data-smark type="text" name="name" placeholder="User name">
      <ul data-smark='{"type":"list","name":"phones"}'>
        <li>
          <input type="tel" data-smark name="phone" placeholder="Phone">
          <!-- Ctrl+- removes a phone when focus is inside the phones list -->
          <button data-smark='{"action":"removeItem","hotkey":"-"}'>➖ Phone</button>
        </li>
      </ul>
      <button data-smark='{"action":"addItem","context":"phones","hotkey":"+"}'>➕ Add phone</button>
      <!-- Ctrl+- removes a user when focus is at the user level (outside phones) -->
      <button data-smark='{"action":"removeItem","hotkey":"-"}'>➖ Remove user</button>
    </li>
  </ul>
  <button data-smark='{"action":"addItem","context":"users","hotkey":"+"}'>➕ Add user</button>
</div>

/* Hold Ctrl to reveal hotkey hints */
button { position: relative; }
[data-hotkey]::after {
    content: "Ctrl+" attr(data-hotkey);
    position: absolute;
    top: -1.6em;
    left: 50%;
    transform: translateX(-50%);
    font-size: 0.7em;
    background: #333;
    color: #fff;
    padding: 1px 4px;
    border-radius: 3px;
    white-space: nowrap;
}

const myForm = new SmarkForm(document.getElementById("myForm"), {
    "value": {"users":[{"name":"Alice","phones":[{"phone":"555-1234"}]},{"name":"Bob","phones":[{"phone":"555-5678"}]}]}
});

Every example in this section comes with many of the following tabs:

HTML: HTML source code of the example.
CSS: CSS applied (if any).
JS: JavaScript source code of the example.
Preview: Live, sandboxed rendering of the example — fully isolated from the page styles.
Notes: Additional notes and insights for better understanding. Don't miss it‼️

🛠️ Between the tab labels and the content there is always an edit toolbar:

✏️ Edit — activates edit mode: each source tab turns into a syntax-highlighted code editor (powered by Ace) pre-filled with the full, merged source. Changes are sandboxed — the original example is not affected.
📋 Include playground editor — (only visible in edit mode) controls whether the JSON playground editor is included in the preview. When toggled, the HTML and JS editors update instantly so you can see exactly what code is needed to add or remove it. Disabled for this example.
▶️ Run — (only visible in edit mode) re-renders the Preview from the current editor contents and switches to the Preview tab.

When the focus is inside the phones list, pressing Ctrl+- removes a phone. When focus is at the user level (but not inside phones), Ctrl+- removes the user instead.

Conflict Resolution

When two triggers share the same hotkey at the same context level, SmarkForm uses the following priority rules to decide which one fires:

Distance from focus — triggers whose context is a closer ancestor of the focused element are preferred.
Containment — when distance is equal, a trigger whose target contains the focused element takes precedence over a sibling trigger.

Only the highest-priority trigger for each key is revealed and activated. Lower-priority duplicates are silently ignored.

A trigger that is disabled at the moment the hotkey is pressed will not fire, even if it was revealed. The data-hotkey attribute is also omitted from disabled buttons so they do not appear in the visual hints.

Accessibility Considerations

Avoid browser-reserved combinations — Ctrl+C, Ctrl+V, Ctrl+Z, Ctrl+A, F1–F12, Alt+F4, etc. are used by browsers and operating systems. Prefer punctuation characters (+, -, n, d, …) that are not typically claimed.
Provide visible alternatives — hotkeys are a convenience feature. Every action that has a hotkey should also be reachable with the mouse so that users on touch devices or those who do not discover the hotkeys can still operate the form.
Label your buttons — use title attributes or visible text on trigger buttons so their purpose is clear even without hotkey hints.

Further Examples

The Showcase contains exhaustive real-world examples that demonstrate hotkeys in context, including nested lists, multi-level hotkey levels, and mixed trigger layouts.

Importing and Exporting Data

⏩