hs.keyboard
ModuleModule for querying and controlling CapsLock state, and for enumerating attached keyboards and controlling their LEDs individually.
Properties
This module has no properties.
Methods
hs.keyboard.capsLockState() -> boolean
Checks the system-wide state of CapsLock.
This reflects a single, global lock state shared by every attached keyboard — macOS has
no public API to query the functional (character-affecting) CapsLock state independently
per keyboard. For a genuinely per-keyboard signal, see `keyboardCapsLockState()`, which
reads each keyboard's own CapsLock LED.
Declaration
hs.keyboard.capsLockState() -> booleanReturns
boolean
true if CapsLock is currently on, false otherwise
Example
console.log(hs.keyboard.capsLockState())hs.keyboard.setCapsLockState(state) -> boolean
Sets the system-wide state of CapsLock.
Declaration
hs.keyboard.setCapsLockState(state) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| state | boolean | true to turn CapsLock on, false to turn it off |
Returns
boolean
The new state, or false if the change could not be applied
Example
hs.keyboard.setCapsLockState(true)hs.keyboard.toggleCapsLockState() -> boolean
Toggles the system-wide state of CapsLock.
Declaration
hs.keyboard.toggleCapsLockState() -> booleanReturns
boolean
The new state, or false if the change could not be applied
Example
hs.keyboard.toggleCapsLockState()hs.keyboard.setLED(name, state) -> boolean
Sets a keyboard LED on every attached keyboard that has one.
Declaration
hs.keyboard.setLED(name, state) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| name | string | The LED to set — one of `"caps"`, `"scroll"`, or `"num"` |
| state | boolean | true to turn the LED on, false to turn it off |
Returns
boolean
true if the LED was successfully set on at least one keyboard
Notes
Requires Input Monitoring permission — see `hs.permissions.requestInputMonitoring()`.
Example
hs.keyboard.setLED("caps", true)hs.keyboard.attachedKeyboards() -> [[String: Any]]
Returns all currently attached keyboard HID devices.
Each object has `keyboardID` (number — pass to `keyboardCapsLockState()`/`setKeyboardLED()`),
`productName` (string), `vendorName` (string), `productID` (number), and `vendorID` (number).
`serialNumber` (string) and `locationID` (number) are included when available.
Declaration
hs.keyboard.attachedKeyboards() -> [[String: Any]]Returns
[[String: Any]]
An array of objects describing each attached keyboard
Example
const keyboards = hs.keyboard.attachedKeyboards()
keyboards.forEach(k => console.log(k.vendorName + " " + k.productName))hs.keyboard.keyboardCapsLockState(keyboardID) -> boolean
Checks a specific keyboard's own CapsLock LED state.
Unlike `capsLockState()`, this queries the individual keyboard identified by `keyboardID`
(from `attachedKeyboards()`), reflecting how modern macOS tracks CapsLock independently per
physical keyboard.
Declaration
hs.keyboard.keyboardCapsLockState(keyboardID) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| keyboardID | number | A keyboard identifier, as returned by `attachedKeyboards()` |
Returns
boolean
true if that keyboard's CapsLock LED is on, false if it is off, unavailable, or the keyboard was not found
Notes
Requires Input Monitoring permission — see `hs.permissions.requestInputMonitoring()`.
Example
const keyboards = hs.keyboard.attachedKeyboards()
if (keyboards.length > 0) {
console.log(hs.keyboard.keyboardCapsLockState(keyboards[0].keyboardID))
}hs.keyboard.setKeyboardLED(keyboardID, name, state) -> boolean
Sets a specific keyboard's LED, leaving all other attached keyboards untouched.
Declaration
hs.keyboard.setKeyboardLED(keyboardID, name, state) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| keyboardID | number | A keyboard identifier, as returned by `attachedKeyboards()` |
| name | string | The LED to set — one of `"caps"`, `"scroll"`, or `"num"` |
| state | boolean | true to turn the LED on, false to turn it off |
Returns
boolean
true if the LED was successfully set
Notes
Requires Input Monitoring permission — see `hs.permissions.requestInputMonitoring()`.
Example
const keyboards = hs.keyboard.attachedKeyboards()
if (keyboards.length > 0) {
hs.keyboard.setKeyboardLED(keyboards[0].keyboardID, "caps", true)
}