hs.hotkey
ModuleModule for creating and managing system-wide hotkeys
Types
This module provides the following types:
Properties
hs.hotkey.alertDuration
number
Duration in seconds for the on-screen toast shown when a hotkey with a
`message` set fires. Default is 1.
Methods
hs.hotkey.bind(mods, key, onPressed, onReleased, onRepeat) -> HSHotkey
Bind a hotkey
`cmd` / `command` / `⌘`, `shift` / `⇧`, `alt` / `option` / `⌥`, `ctrl` / `control` / `⌃`.
Declaration
hs.hotkey.bind(mods, key, onPressed, onReleased, onRepeat) -> 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") |
| onPressed | function | A JavaScript function to call when the hotkey is pressed, or null for no callback |
| onReleased | function | A JavaScript function to call when the hotkey is released, or null/omitted for no callback |
| onRepeat | function | A JavaScript function to call repeatedly while the hotkey is held down, or null/omitted for no repeat |
Returns
HSHotkey
A hotkey object, or null if binding failed (including when none of the callbacks is a function — at least one is required)
Example
hs.hotkey.bind(["cmd","shift"], "h", () => {
console.log("Hello!")
}, null, () => console.log("still held"))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, onPressed, onReleased, onRepeat) -> HSHotkey
Create a hotkey without enabling it
`cmd` / `command` / `⌘`, `shift` / `⇧`, `alt` / `option` / `⌥`, `ctrl` / `control` / `⌃`.
Declaration
hs.hotkey.create(mods, key, onPressed, onReleased, onRepeat) -> 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") |
| onPressed | function | A JavaScript function to call when the hotkey is pressed, or null for no callback |
| onReleased | function | A JavaScript function to call when the hotkey is released, or null/omitted for no callback |
| onRepeat | function | A JavaScript function to call repeatedly while the hotkey is held down, or null/omitted for no repeat |
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!")
})
hk.enable()hs.hotkey.getHotkeys() -> [[String: Any]]
Get a list of all currently-enabled hotkeys
Declaration
hs.hotkey.getHotkeys() -> [[String: Any]]Returns
[[String: Any]]
An array of objects, each with `mods`, `key`, `message` and `enabled` fields
Example
console.log(hs.hotkey.getHotkeys())hs.hotkey.systemAssigned(mods, key) -> [String: Any]
Check whether macOS itself has already claimed a key combination (e.g. for Spotlight, screenshots, etc.)
Declaration
hs.hotkey.systemAssigned(mods, key) -> [String: Any]Parameters
| Name | Type | Description |
|---|---|---|
| mods | string[] | An array of modifier key strings |
| key | string | The key name or character |
Returns
[String: Any]
An object with `keyCode`, `mods` and `enabled` fields if the combination is system-assigned, otherwise null
Example
console.log(hs.hotkey.systemAssigned(["cmd","space"], "space"))hs.hotkey.assignable(mods, key) -> boolean
Check whether a key combination is available to be bound (i.e. not already claimed by macOS)
Declaration
hs.hotkey.assignable(mods, key) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| mods | string[] | An array of modifier key strings |
| key | string | The key name or character |
Returns
boolean
True if the combination can be bound, otherwise False
Example
console.log(hs.hotkey.assignable(["cmd","shift"], "h"))hs.hotkey.deleteAll(mods, key) -> None
Disable and remove every hotkey currently bound to a key combination
Declaration
hs.hotkey.deleteAll(mods, key) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| mods | string[] | An array of modifier key strings |
| key | string | The key name or character |
Returns
None
Example
hs.hotkey.deleteAll(["cmd","shift"], "h")hs.hotkey.disableAll(mods, key) -> None
Disable every hotkey currently bound to a key combination, without removing them
Declaration
hs.hotkey.disableAll(mods, key) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| mods | string[] | An array of modifier key strings |
| key | string | The key name or character |
Returns
None
Example
hs.hotkey.disableAll(["cmd","shift"], "h")hs.hotkey.bindSpec(spec) -> any
Bind a hotkey from a single options object. Like hs.hotkey.bind()/create(), but also
accepts a `message` and a `repeat` callback. `message` is available on any hotkey (not
just ones created via bindSpec()) by setting `.message` directly on the returned object;
see hs.hotkey's message property for exactly when it is shown.
Declaration
hs.hotkey.bindSpec(spec) -> anyParameters
| Name | Type | Description |
|---|---|---|
| spec | any | An object with the following fields: |
Returns
any
A hotkey object, or null if binding failed
Example
hs.hotkey.bindSpec({
mods: ["cmd"], key: "space", message: "Spotlight-like",
pressed: () => console.log("pressed")
})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 | 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
HSHotkeyModal
A modal object with bind(), enter(), exit(), destroy() methods, isActive property, and onEnter/onExit callbacks
Example
const m = hs.hotkey.createModal(['cmd'], 'h')
m.bind(['shift'], 'j', () => console.log('shift-j pressed'))
m.onEnter = () => console.log('modal entered')
m.onExit = () => console.log('modal exited')
m.bind([], 'escape', () => m.exit())hs.hotkey.showHotkeys(mods, key) -> any
Create and enable a hotkey that, while held down, displays a list of all currently
enabled hotkeys (and their messages, if any) as an on-screen toast.
Declaration
hs.hotkey.showHotkeys(mods, key) -> anyParameters
| Name | Type | Description |
|---|---|---|
| mods | any | Modifier keys for the trigger hotkey (e.g. ["cmd", "shift"]) |
| key | any | Key name for the trigger hotkey (e.g. "/") |
Returns
any
A hotkey object
Example
hs.hotkey.showHotkeys(["cmd","shift"], "/")