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:

<ul data-smark='{"type":"list","name":"users"}'>
    <li>
        <ul data-smark='{"type":"list","name":"phones"}'>
            <li>
                <input type="tel" data-smark>
                <!-- "-" removes a phone when focus is inside the phones list -->
                <button data-smark='{"action":"removeItem","hotkey":"-"}'>➖</button>
            </li>
        </ul>
        <!-- "-" removes a user when focus is inside a user item (but outside phones) -->
        <button data-smark='{"action":"removeItem","hotkey":"-"}'>➖ Remove user</button>
    </li>
</ul>

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

⏩