hs.hotkey
ModuleModule for creating and managing system-wide hotkeys
Types
This module provides the following types:
Properties
This module has no properties.
Methods
hs.hotkey.bind(mods, key, callbackPressed, callbackReleased) -> HSHotkey
Bind a hotkey
(`cmd`, `shift`, `alt`, `ctrl`, `fn`) and side-specific names (`leftCmd`, `rightCmd`,
`leftAlt`, `rightAlt`, `leftCtrl`, `rightCtrl`, `leftShift`, `rightShift`).
Declaration
hs.hotkey.bind(mods, key, callbackPressed, callbackReleased) -> HSHotkeyParameters
| Name | Type | Description |
|---|---|---|
| mods | string[] | An array of modifier key strings (e.g., ["cmd", "shift"]). Supports generic names |
| key | string | The key name or character (e.g., "a", "space", "return", "f1") |
| callbackPressed | function | A JavaScript function to call when the hotkey is pressed, or null for no callback |
| callbackReleased | function | A JavaScript function to call when the hotkey is released, or null for no callback |
Returns
HSHotkey
A hotkey object, or null if binding failed
Example
hs.hotkey.bind(["cmd","shift"], "h", () => {
console.log("Hello!")
})hs.hotkey.bindSpec(mods, key, message, callbackPressed, callbackReleased) -> HSHotkey
Bind a hotkey with a message description
Declaration
hs.hotkey.bindSpec(mods, key, message, callbackPressed, callbackReleased) -> HSHotkeyParameters
| Name | Type | Description |
|---|---|---|
| mods | string[] | An array of modifier key strings |
| key | string | The key name or character |
| message | string | A description of what this hotkey does (currently unused, for future features) |
| callbackPressed | function | A JavaScript function to call when the hotkey is pressed, or null for no callback |
| callbackReleased | function | A JavaScript function to call when the hotkey is released, or null for no callback |
Returns
HSHotkey
A hotkey object, or null if binding failed
Example
hs.hotkey.bindSpec(["cmd"], "space", "Spotlight-like", () => {
console.log("pressed")
}, null)hs.hotkey.getKeyCodeMap() -> {[key: string]: number}
Get the system-wide mapping of key names to key codes
Declaration
hs.hotkey.getKeyCodeMap() -> {[key: string]: number}Returns
{[key: string]: number}
A dictionary mapping key names to numeric key codes
Example
console.log(hs.hotkey.getKeyCodeMap())hs.hotkey.getModifierMap() -> {[key: string]: number}
Get the mapping of modifier names to modifier flags
Declaration
hs.hotkey.getModifierMap() -> {[key: string]: number}Returns
{[key: string]: number}
A dictionary mapping modifier names to their numeric values
Example
console.log(hs.hotkey.getModifierMap())hs.hotkey.createModal(mods, key) -> HSHotkeyModal
Create a new modal hotkey group, optionally entered via a trigger key combination
Declaration
hs.hotkey.createModal(mods, key) -> HSHotkeyModalParameters
| Name | Type | Description |
|---|---|---|
| mods | string[] | Modifier keys for the trigger hotkey (e.g. `["cmd", "shift"]`), or an empty array for no trigger |
| key | string | Key name for the trigger hotkey (e.g. `"h"`), or an empty string for no trigger |
Returns
HSHotkeyModal
A new modal object. If a non-empty key is given but cannot be resolved, a warning is logged and the modal is returned without a trigger.
Example
// Modal with a Cmd+H trigger — pressing it calls enter() automatically
const m = hs.hotkey.createModal(['cmd'], 'h')
m.bind(['shift'], 'j', () => console.log('shift-j pressed'), null)
m.enterFn = () => console.log('modal entered')
m.exitFn = () => console.log('modal exited')
// Modal with no trigger — enter/exit manually
const m2 = hs.hotkey.createModal([], '')
m2.enter()