hs.keycodes
ModuleAccess information about the current keyboard layout and input sources, and respond to changes.
Reading the current layout
console.log("Layout: " + hs.keycodes.currentLayout())
console.log("Source ID: " + hs.keycodes.currentSourceID())
Key code mapping
// Look up a keycode by name
const code = hs.keycodes.map["a"] // e.g. 0 on ANSI US
// Look up a name by keycode
const name = hs.keycodes.map["0"] // e.g. "a"
Switching layouts
hs.keycodes.setLayout("British")
Watching for input source changes
hs.keycodes.on('change', () => {
console.log("Switched to: " + hs.keycodes.currentLayout())
})
Properties
hs.keycodes.map
{[key: string]: any}
A bidirectional mapping between key names and their macOS virtual key codes.
Entries exist for both directions: look up a name to get its integer keycode, or look
up a keycode (as a string) to get the key name. The map is rebuilt automatically
whenever the keyboard input source changes.
Methods
hs.keycodes.currentLayout() -> string
Returns the localized name of the current keyboard layout.
Uses the base keyboard layout, which is the underlying layout even when an input
method (such as a CJK input method) is also active.
Declaration
hs.keycodes.currentLayout() -> stringReturns
string
The display name of the active layout (e.g. `"U.S."`, `"British"`), or `null`.
Example
console.log("Layout: " + hs.keycodes.currentLayout())hs.keycodes.currentMethod() -> string
Returns the localized name of the active input method, or `null` if none is active.
Input methods are distinct from keyboard layouts. They provide complex character
composition such as CJK input. Returns `null` when using a plain keyboard layout
with no input method overlay.
Declaration
hs.keycodes.currentMethod() -> stringReturns
string
The display name of the active input method (e.g. `"Hiragana"`), or `null`.
Example
const m = hs.keycodes.currentMethod()
if (m) console.log("Input method: " + m)hs.keycodes.currentSourceID() -> string
Returns the reverse-DNS identifier of the currently selected keyboard input source.
Declaration
hs.keycodes.currentSourceID() -> stringReturns
string
A string such as `"com.apple.keylayout.US"`, or `null` if unavailable.
Example
console.log("Source ID: " + hs.keycodes.currentSourceID())hs.keycodes.layouts() -> string[]
Returns the localized names of all currently enabled keyboard layouts.
Declaration
hs.keycodes.layouts() -> string[]Returns
string[]
An array of layout name strings (e.g. `["U.S.", "British", "French"]`).
Example
hs.keycodes.layouts().forEach(l => console.log(l))hs.keycodes.methods() -> string[]
Returns the localized names of all currently enabled input methods.
Declaration
hs.keycodes.methods() -> string[]Returns
string[]
An array of input method name strings. May be empty if none are enabled.
Example
hs.keycodes.methods().forEach(m => console.log(m))hs.keycodes.setLayout(layoutName) -> boolean
Switches the active keyboard layout to the one with the given localized name.
Use `layouts()` to enumerate valid names.
Declaration
hs.keycodes.setLayout(layoutName) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| layoutName | string | The localized name of the layout to activate (e.g. `"U.S."`). |
Returns
boolean
`true` if the layout was found and selected, `false` otherwise.
Example
if (!hs.keycodes.setLayout("U.S.")) console.log("Layout not found")hs.keycodes.setMethod(methodName) -> boolean
Switches the active input method to the one with the given localized name.
Use `methods()` to enumerate valid names.
Declaration
hs.keycodes.setMethod(methodName) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| methodName | string | The localized name of the input method to activate. |
Returns
boolean
`true` if the method was found and selected, `false` otherwise.
Example
hs.keycodes.setMethod("Hiragana")hs.keycodes.setSourceID(sourceID) -> boolean
Switches the active input source to the one with the given reverse-DNS identifier.
Use `currentSourceID()` to see the current value.
Declaration
hs.keycodes.setSourceID(sourceID) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| sourceID | string | The input source ID to activate (e.g. `"com.apple.keylayout.British"`). |
Returns
boolean
`true` if the source was found and selected, `false` otherwise.
Example
hs.keycodes.setSourceID("com.apple.keylayout.British")hs.keycodes.on(event, listener) -> None
Register a listener that fires whenever the keyboard input source changes.
Read `currentLayout()`, `currentSourceID()`, or `map` inside the listener to inspect the new
state.
Declaration
hs.keycodes.on(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event to listen for (the only event this module emits) |
| listener | any | Called with no arguments when the input source changes |
Returns
None
Throws
Throws an Error on failure; wrap calls in try/catch to handle it.
Example
try {
hs.keycodes.on('change', () => console.log("Now using: " + hs.keycodes.currentLayout()))
} catch (err) {
console.error(err.message)
}hs.keycodes.off(event, listener) -> None
Remove a previously registered input source change listener.
Declaration
hs.keycodes.off(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event the listener was registered for |
| listener | any | The function originally passed to `on` |
Returns
None
Example
const onChange = () => console.log("changed")
hs.keycodes.on('change', onChange)
// later…
hs.keycodes.off('change', onChange)hs.keycodes.once(event, listener) -> None
Register a listener that fires at most once, the next time the keyboard input source changes.
Declaration
hs.keycodes.once(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event to listen for |
| listener | any | Called once, then automatically removed |
Returns
None
Throws
Throws an Error on failure; wrap calls in try/catch to handle it.
Example
try {
hs.keycodes.once('change', () => console.log("First change detected"))
} catch (err) {
console.error(err.message)
}