hs.mouse
ModuleControl and inspect the mouse pointer and attached mouse devices.
Position
All coordinates use Hammerspoon screen coordinates: (0, 0) is at the top-left
of the primary display and y increases downward.
const pos = hs.mouse.absolutePosition()
console.log("Mouse at " + pos.x + ", " + pos.y)
hs.mouse.setAbsolutePosition(100, 200)
Device info
console.log("Mice: " + hs.mouse.count())
hs.mouse.names().forEach(n => console.log(n))
Cursor
console.log(hs.mouse.currentCursorType()) // e.g. "arrow"
console.log(hs.mouse.scrollDirection()) // "natural" or "normal"
Properties
This module has no properties.
Methods
hs.mouse.absolutePosition() -> {[key: string]: number}
Returns the current mouse pointer position in Hammerspoon screen coordinates.
Hammerspoon coordinates have `(0, 0)` at the top-left of the primary display,
with `y` increasing downward.
Declaration
hs.mouse.absolutePosition() -> {[key: string]: number}Returns
{[key: string]: number}
An object with `x` and `y` number properties.
Example
const pos = hs.mouse.absolutePosition()
console.log("x=" + pos.x + " y=" + pos.y)hs.mouse.setAbsolutePosition(x, y) -> None
Moves the mouse pointer to the specified absolute position in Hammerspoon screen coordinates.
Declaration
hs.mouse.setAbsolutePosition(x, y) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| x | number | Horizontal position; `0` is the left edge of the primary display. |
| y | number | Vertical position; `0` is the top edge of the primary display. |
Returns
None
Example
hs.mouse.setAbsolutePosition(100, 200)hs.mouse.getRelativePosition() -> [String: Double]
Returns the mouse pointer position relative to the screen it is currently on.
The returned coordinates have `(0, 0)` at the top-left corner of the screen
that the cursor is on.
Declaration
hs.mouse.getRelativePosition() -> [String: Double]Returns
[String: Double]
An object with `x` and `y` number properties, or `null` if no screen can be determined.
Example
const rel = hs.mouse.getRelativePosition()
if (rel) console.log("x=" + rel.x + " y=" + rel.y)hs.mouse.setRelativePosition(x, y) -> None
Moves the mouse pointer to a position relative to the screen it is currently on.
Declaration
hs.mouse.setRelativePosition(x, y) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| x | number | Horizontal offset from the current screen's left edge. |
| y | number | Vertical offset from the current screen's top edge. |
Returns
None
Example
hs.mouse.setRelativePosition(0, 0) // move to top-left of current screenhs.mouse.getCurrentScreen() -> HSScreen
Returns the screen that the mouse pointer is currently on.
Declaration
hs.mouse.getCurrentScreen() -> HSScreenReturns
HSScreen
An HSScreen object for the display containing the cursor, or `null` if none can be determined.
Example
const s = hs.mouse.getCurrentScreen()
if (s) console.log("Mouse is on: " + s.name)hs.mouse.count(includeInternal) -> number
Returns the number of mouse devices currently attached to the system.
Declaration
hs.mouse.count(includeInternal) -> numberParameters
| Name | Type | Description |
|---|---|---|
| includeInternal | boolean | When `true`, built-in pointing devices (e.g. the MacBook built-in trackpad) are included. Defaults to `false`. |
Returns
number
The number of attached mouse devices.
Example
console.log("External mice: " + hs.mouse.count())
console.log("All pointing devices: " + hs.mouse.count(true))hs.mouse.names(includeInternal) -> string[]
Returns the product names of all mouse devices currently attached to the system.
Declaration
hs.mouse.names(includeInternal) -> string[]Parameters
| Name | Type | Description |
|---|---|---|
| includeInternal | boolean | When `true`, built-in pointing devices are included. Defaults to `false`. |
Returns
string[]
An array of product name strings.
Example
hs.mouse.names().forEach(n => console.log(n))hs.mouse.trackingSpeed() -> number
Returns the current mouse tracking speed (acceleration level).
Values range from `-1.0` (system default, acceleration disabled) to `3.0` (maximum acceleration).
Returns `-1.0` if the value cannot be read.
Declaration
hs.mouse.trackingSpeed() -> numberReturns
number
The current tracking speed as a number.
Example
console.log("Tracking speed: " + hs.mouse.trackingSpeed())hs.mouse.setTrackingSpeed(speed) -> None
Sets the mouse tracking speed (acceleration level).
The change takes effect immediately for the current login session and is also persisted
to preferences so it survives a restart. Values outside the valid range or non-finite
values are rejected with a warning and no change is made.
Declaration
hs.mouse.setTrackingSpeed(speed) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| speed | number | Desired tracking speed in the range `-1.0` to `3.0`. |
Returns
None
Example
hs.mouse.setTrackingSpeed(1.5)hs.mouse.scrollDirection() -> string
Returns the current scroll wheel direction setting.
Declaration
hs.mouse.scrollDirection() -> stringReturns
string
`"natural"` if content scrolls in the same direction as the finger/wheel movement (macOS default), or `"normal"` for the traditional direction.
Example
console.log(hs.mouse.scrollDirection())hs.mouse.currentCursorType() -> string
Returns the name of the cursor type currently set by this application.
has the keyboard focus, the visible system cursor may differ.
Declaration
hs.mouse.currentCursorType() -> stringReturns
string
A string such as `"arrow"`, `"iBeam"`, `"crosshair"`, `"pointingHand"`,
Notes
This reflects the cursor set by the Hammerspoon process. If another application
Example
console.log(hs.mouse.currentCursorType())