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` / `command` / `⌘`, `shift` / `⇧`, `alt` / `option` / `⌥`, `ctrl` / `control` / `⌃`.
Declaration
hs.hotkey.bind(mods, key, callbackPressed, callbackReleased) -> HSHotkeyParameters
| Name | Type | Description |
|---|---|---|
| mods | string[] | An array of modifier key strings (e.g., `["cmd", "shift"]`). Supported 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!")
}, null)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.create(mods, key, callbackPressed, callbackReleased) -> HSHotkey
Create a hotkey without enabling it
`cmd` / `command` / `⌘`, `shift` / `⇧`, `alt` / `option` / `⌥`, `ctrl` / `control` / `⌃`.
Declaration
hs.hotkey.create(mods, key, callbackPressed, callbackReleased) -> HSHotkeyParameters
| Name | Type | Description |
|---|---|---|
| mods | string[] | An array of modifier key strings (e.g., `["cmd", "shift"]`). Supported 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 creation failed. Call `.enable()` to activate it.
Example
const hk = hs.hotkey.create(["cmd","shift"], "h", () => {
console.log("Hello!")
}, null)
hk.enable()hs.hotkey.createModal(mods, key) -> any
Create a new modal hotkey group, optionally entered via a trigger key combination
Declaration
hs.hotkey.createModal(mods, key) -> anyParameters
| Name | Type | Description |
|---|---|---|
| mods | any | Modifier keys for the trigger hotkey (e.g. ["cmd", "shift"]), or an empty array for no trigger |
| key | any | Key name for the trigger hotkey (e.g. "h"), or an empty string for no trigger |
Returns
any
A modal object with bind(), enter(), exit(), destroy() methods, isActive property, and enterFn/exitFn callbacks
Example
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')
m.bind([], 'escape', () => m.exit(), null)