HSScreen
TypeAn object representing a single display attached to the system.
Coordinate system
All geometry is returned in Hammerspoon screen coordinates: the origin (0, 0)
is at the top-left of the primary display, and y increases downward.
This matches Hammerspoon v1 and is the inverse of the raw macOS/CoreGraphics convention.
Examples
const s = hs.screen.main();
console.log(s.name); // e.g. "Built-in Retina Display"
console.log(s.frame.w); // usable width in points
console.log(s.mode.width, s.mode.scale); // e.g. 1440, 2
s.desktopImage = "/Users/me/wallpaper.jpg";
Properties
fullFrame
HSRect
The full screen area in Hammerspoon coordinates, including menu bar and Dock regions.
mode
NSDictionary
The currently active display mode.
An object with keys: `width`, `height`, `scale`, `frequency`.
availableModes
NSDictionary[]
All display modes supported by this screen.
Each element has keys: `width`, `height`, `scale`, `frequency`.
rotation
number
The current screen rotation in degrees (0, 90, 180, or 270).
Assign one of `0`, `90`, `180`, or `270` to rotate the display.
desktopImage
string
The URL string of the current desktop background image for this screen, or `null`.
Assign a new absolute file path or `file://` URL string to change the wallpaper.
Methods
setMode(width, height, scale, frequency) -> boolean
Switch to the given display mode.
Pass `0` for `scale` or `frequency` to match any value.
Declaration
setMode(width, height, scale, frequency) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| width | number | Horizontal resolution in pixels. |
| height | number | Vertical resolution in pixels. |
| scale | number | Backing scale factor (e.g. `2` for HiDPI, `1` for non-HiDPI). Pass `0` to ignore. |
| frequency | number | Refresh rate in Hz. Pass `0` to ignore. |
Returns
boolean
`true` on success.
Example
const s = hs.screen.primary()
s.setMode(1920, 1080, 1, 60)snapshot() -> Promise<HSImage>
Capture the current contents of this screen as an image.
Requires **Screen Recording** permission.
Declaration
snapshot() -> Promise<HSImage>Returns
Promise<HSImage>
Resolves with the captured image, or rejects if the capture fails (e.g. permission denied).
Example
hs.screen.main().snapshot().then(img => img.saveToFile("/tmp/screen.png"))next() -> HSScreen
The next screen in `hs.screen.all()` order, wrapping around.
Declaration
next() -> HSScreenReturns
HSScreen
An HSScreen object
Example
const next = hs.screen.main().next()previous() -> HSScreen
The previous screen in `hs.screen.all()` order, wrapping around.
Declaration
previous() -> HSScreenReturns
HSScreen
An HSScreen object
Example
const prev = hs.screen.main().previous()toEast() -> HSScreen
The nearest screen whose left edge is at or beyond this screen's right edge, or `null`.
Declaration
toEast() -> HSScreenReturns
HSScreen
An HSScreen object
Example
const right = hs.screen.main().toEast()toWest() -> HSScreen
The nearest screen whose right edge is at or before this screen's left edge, or `null`.
Declaration
toWest() -> HSScreenReturns
HSScreen
An HSScreen object
Example
const left = hs.screen.main().toWest()toNorth() -> HSScreen
The nearest screen that is physically above this screen, or `null`.
Declaration
toNorth() -> HSScreenReturns
HSScreen
An HSScreen object
Example
const above = hs.screen.main().toNorth()toSouth() -> HSScreen
The nearest screen that is physically below this screen, or `null`.
Declaration
toSouth() -> HSScreenReturns
HSScreen
An HSScreen object
Example
const below = hs.screen.main().toSouth()setOrigin(x, y) -> boolean
Move this screen so its top-left corner is at the given position in global Hammerspoon coordinates.
Declaration
setOrigin(x, y) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| x | number | The X coordinate to move to |
| y | number | The Y coordinate to move to |
Returns
boolean
`true` on success.
Example
const s = hs.screen.primary()
s.setOrigin(0, 0)setPrimary() -> boolean
Designate this screen as the primary display (moves the menu bar here).
Declaration
setPrimary() -> booleanReturns
boolean
`true` on success.
Example
hs.screen.all()[1].setPrimary()mirrorOf(screen) -> boolean
Configure this screen to mirror another screen.
Declaration
mirrorOf(screen) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| screen | HSScreen | The screen to mirror. |
Returns
boolean
`true` on success.
Example
const all = hs.screen.all()
all[1].mirrorOf(all[0])mirrorStop() -> boolean
Stop mirroring, restoring this screen to an independent display.
Declaration
mirrorStop() -> booleanReturns
boolean
`true` on success.
Example
hs.screen.all()[1].mirrorStop()absoluteToLocal(rect) -> HSRect
Convert a rect in global Hammerspoon coordinates to coordinates local to this screen.
The result origin is relative to this screen's top-left corner.
Declaration
absoluteToLocal(rect) -> HSRectParameters
| Name | Type | Description |
|---|---|---|
| rect | JSValue | An `HSRect` in global Hammerspoon coordinates. |
Returns
HSRect
The rect offset to be relative to this screen's top-left, or `null` if the input is invalid.
Example
const s = hs.screen.main()
const local = s.absoluteToLocal({x: 1000, y: 500, w: 200, h: 100})localToAbsolute(rect) -> HSRect
Convert a rect in local screen coordinates to global Hammerspoon coordinates.
Declaration
localToAbsolute(rect) -> HSRectParameters
| Name | Type | Description |
|---|---|---|
| rect | JSValue | An `HSRect` relative to this screen's top-left corner. |
Returns
HSRect
The rect in global Hammerspoon coordinates, or `null` if the input is invalid.
Example
const s = hs.screen.main()
const abs = s.localToAbsolute({x: 10, y: 10, w: 100, h: 100})