Hotkey
Runs the macro when you press a key combination, or tap modifier keys on their own.
hotkey is pressed
Keyboard Maestro: HotKey
Details #
By default fires when the key combination goes down (phase pressed). Switchboard listens through a keyboard tap, so the hotkey works in every app, and a key press that belongs to a macro is swallowed: the front app never sees it.
keys is the key and modifiers are the modifiers. Modifier names are cmd, ctrl, opt, shift, fn and hyper (Command, Control, Option and Shift together). The key is matched by the character it types on your current keyboard layout; named keys (return, tab, space, arrows, F-keys) never move. Leave keys empty to bind modifiers alone, for example Hyper tapped on its own. A modifier-only hotkey fires when you release the modifiers, and only if no other key was pressed in between.
Arrow, function and navigation keys carry the Fn flag on their own. You do not need to add fn for them.
{{triggerValue}} holds the key name of the key that was pressed (for example k or return), without modifiers. It is empty for a modifier-only hotkey.
Holding the key. A held key repeats. By default only the first press runs the macro; the repeats are swallowed but ignored. Set repeat to true to run once per repeat.
Phase. phase picks the moment: pressed (the default), released (when the key comes up), tapped (released within 0.35 seconds; taps counts taps in a row, each within 0.45 seconds of the last, default 1), tappedOnly (matched the same way as tapped) and longPressed (once, when the key has been held for half a second). The key press is swallowed whatever the phase. repeat only applies to pressed. A modifier-only hotkey works only with pressed.
Hold to talk. hold: true makes the run follow the key: it starts when the key goes down, and a step that waits for the key to come up (the Dictate step, stop: release) sees it come up. A press shorter than a quarter second counts as a mistake there. Only for pressed. See Dictation: hold to talk.
Secure input. macOS blocks key events while a password field has focus. If secure input is on when a hotkey would fire, nothing runs and the Not fired list records the reason secureInput, naming the app that probably holds it. The menu bar also says "Secure input is on".
Conflicts. Two enabled macros with the same hotkey in overlapping scopes do not run. Instead the Conflict palette opens, titled with the key combination, and you pick the one to run (↑ ↓ to move, ⏎ to choose, Esc to cancel). The check on your Only if conditions happens after you pick. The library check flags the same clash as an error before it happens. A hotkey in a Group scoped to specific apps beats the same hotkey in an Everywhere group when one of those apps is in front.
Scope. The Group's scope decides: Everywhere, only named apps, or everywhere except named apps. Out of scope, the key goes through to the app untouched and nothing is recorded.
Permission. Needs Input Monitoring. Without it the keyboard source shows as refused and no hotkey or typed trigger works.
Parameters #
| Parameter | Type | Required | Values | What it does |
|---|---|---|---|---|
keys | text | Yes | One key, as a character or a name (k, 4, return, f5, keypad5, space). Letters are not case sensitive. | |
modifiers | list of | Yes | cmd ctrl opt shift fn hyper | The modifiers that must be down, and no others. Pass [] for none. An extra modifier held means no match. |
hold | yes / no | Fire as the key goes down and let a running Dictate step see it come up. Only for pressed. | ||
phase | one of | pressed released tapped tappedOnly longPressed | pressed (default), released, tapped, tappedOnly or longPressed. | |
repeat | yes / no | Run again for every key repeat while the key is held. Off by default. | ||
taps | whole number | With tapped or tappedOnly, how many taps in a row. Default 1. |
Every trigger also takes Limits: a cooldown, the first time each day, every nth time, twice within seconds, a chance, only while you are at the Mac, on one Mac, or in a State. See Limits on any trigger.
Examples #
- Press ✦K
- Show “You pressed {{triggerValue}}”
- Press fn
- Show “Fn tapped”
Gotchas #
A hotkey with no modifiers (
J) is for macros in a Group with a Layer: it answers only while the layer is live. Anywhere else the library check refuses it. See Layers.Held modifiers must match exactly.
cmd+shift+kdoes not fire when you also hold Option.The key press is swallowed only while the macro is enabled, its Group is on, and the front app is in scope.
Not fired reasons that apply:
conflict,secureInputandconditionFalse. A hotkey whose macro is off, whose Group is off or out of scope, or that is paused is not claimed: the key goes straight through and nothing is recorded. Repeats of a held key are never recorded.