API Docs

HSUIWindow

Type

HSUIWindow

A custom window with declarative UI building

HSUIWindow allows you to create custom windows with a SwiftUI-like declarative syntax. Build interfaces using shapes, text, images, and layout containers.

** Note: ** Clicking the macOS close button only hides the window (firing the onHide() callback, if you have one configured) — it does not destroy the window while you hold a reference to it in JavaScript. Call destroy() explicitly (for example from within an onHide() handler) if you want to release it. See onShow(), onHide(), and onDestroy() below for the full set of lifecycle callbacks.

Building UI Elements

  • Shapes: rectangle(), circle()
  • Text: text(content)
  • Buttons: button(label) — uses SwiftUI's native Button for press-state feedback
  • Images: image(imageValue)
  • Video: video(videoValue)
  • Layout: vstack(), hstack(), zstack(), spacer()

Modifying Elements

  • Shape modifiers: fill(), stroke(), strokeWidth(), cornerRadius()
  • Text modifiers: font(), foregroundColor()
  • Image modifiers: resizable(), aspectRatio(mode)
  • Layout modifiers: frame(), opacity(), padding(), spacing()

Examples

Simple window with text and shapes:

hs.ui.window({x: 100, y: 100, w: 300, h: 200})
    .vstack()
        .spacing(10)
        .padding(20)
        .text("Dashboard")
            .font(HSFont.largeTitle())
            .foregroundColor("#FFFFFF")
        .rectangle()
            .fill("#4A90E2")
            .cornerRadius(10)
            .frame({w: "90%", h: 80})
    .end()
    .backgroundColor("#2C3E50")
    .show();

Window with image:

const img = HSImage.fromPath("~/Pictures/photo.jpg")
hs.ui.window({x: 100, y: 100, w: 400, h: 300})
    .vstack()
        .padding(20)
        .image(img)
            .resizable()
            .aspectRatio("fit")
            .frame({w: 360, h: 240})
    .end()
    .show();

Properties

This type has no properties.

Methods

show() -> HSUIWindow

Show the window
Declaration
show() -> HSUIWindow
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:80

hide() -> None

Hide the window (keeps it in memory)
Declaration
hide() -> None
Returns
None
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:83

destroy() -> None

Destroy the window
Declaration
destroy() -> None
Returns
None
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:86

onShow(callback) -> HSUIWindow

Set a callback to fire after the window is shown
Declaration
onShow(callback) -> HSUIWindow
Parameters
Name Type Description
callback function A JavaScript function called after the window becomes visible
Returns
HSUIWindow
Self for chaining
Example
hs.ui.window({x: 100, y: 100, w: 300, h: 200})
    .text("Hello")
    .onShow(() => console.log("Window shown"))
    .show()
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:98

onHide(callback) -> HSUIWindow

Set a callback to fire when the window is hidden Fires when `hide()` is called, **and** when the user clicks the macOS close button — clicking that button only hides the window from Hammerspoon's perspective (see the class-level note above), so this is the callback that reacts to it. Does not fire when the window is destroyed via `destroy()` — use `onDestroy()` for that.
Declaration
onHide(callback) -> HSUIWindow
Parameters
Name Type Description
callback function A JavaScript function called after the window is hidden
Returns
HSUIWindow
Self for chaining
Example
const win = hs.ui.window({x: 100, y: 100, w: 300, h: 200})
    .text("Hello")
    .onHide(() => console.log("Window hidden (via hide() or the close button)"))
    .show()
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:117

onDestroy(callback) -> HSUIWindow

Set a callback to fire after the window is destroyed via `destroy()` Only fires when `destroy()` is called explicitly — whether directly, or from within an `onHide()` handler. It does **not** fire when the user clicks the macOS close button by itself; that only hides the window, so use `onHide()` to react to the button click, and call `destroy()` from that handler if you also want to release the window.
Declaration
onDestroy(callback) -> HSUIWindow
Parameters
Name Type Description
callback function A JavaScript function called after the window is destroyed
Returns
HSUIWindow
Self for chaining
Example
const win = hs.ui.window({x: 100, y: 100, w: 300, h: 200})
    .text("Hello")
    .onDestroy(() => console.log("Window destroyed"))
    .show()
win.destroy()
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:137

titled(show) -> HSUIWindow

Show or hide the window's title bar By default windows have a title bar. Pass `false` to create a borderless window. `.closable()`, `.miniaturizable()`, and `.allowResize()` only take visual effect when the window is titled.
Declaration
titled(show) -> HSUIWindow
Parameters
Name Type Description
show boolean Pass `false` to make the window borderless
Returns
HSUIWindow
Self for chaining
Example
// Borderless floating overlay
hs.ui.window({x: 100, y: 100, w: 400, h: 300})
    .titled(false)
    .level("floating")
    .show()
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:157

closable(show) -> HSUIWindow

Show or hide the close button on the window Requires `.titled(true)` to be visible. Enabled by default.
Declaration
closable(show) -> HSUIWindow
Parameters
Name Type Description
show boolean Pass `false` to hide the close button
Returns
HSUIWindow
Self for chaining
Example
hs.ui.window({x: 100, y: 100, w: 800, h: 600})
    .closable(false).show()
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:170

miniaturizable(show) -> HSUIWindow

Show or hide the miniaturize (yellow) button on the window Requires `.titled(true)` to be visible. Enabled by default.
Declaration
miniaturizable(show) -> HSUIWindow
Parameters
Name Type Description
show boolean Pass `false` to hide the miniaturize button
Returns
HSUIWindow
Self for chaining
Example
hs.ui.window({x: 100, y: 100, w: 800, h: 600})
    .miniaturizable(false).show()
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:183

allowResize(enable) -> HSUIWindow

Allow or prevent the user from resizing the window Enabled by default. Only has a visual effect when `.titled(true)` is also set.
Declaration
allowResize(enable) -> HSUIWindow
Parameters
Name Type Description
enable boolean Pass `false` to prevent the user from resizing the window
Returns
HSUIWindow
Self for chaining
Example
hs.ui.window({x: 100, y: 100, w: 800, h: 600})
    .allowResize(false).show()
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:196

windowTitle(text) -> HSUIWindow

Set the text shown in the window's title bar Only visible when `.titled(true)` is set (the default).
Declaration
windowTitle(text) -> HSUIWindow
Parameters
Name Type Description
text string The title bar text
Returns
HSUIWindow
Self for chaining
Example
hs.ui.window({x: 100, y: 100, w: 800, h: 600})
    .windowTitle("My Browser").show()
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:209

level(name) -> HSUIWindow

Set the window stacking level Controls where this window sits in the macOS window hierarchy.
Declaration
level(name) -> HSUIWindow
Parameters
Name Type Description
name string The level name
Returns
HSUIWindow
Self for chaining
Example
hs.ui.window({x: 100, y: 100, w: 800, h: 600})
    .level("floating").show()
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:229

backgroundColor(colorValue) -> HSUIWindow

Set the window's background color
Declaration
backgroundColor(colorValue) -> HSUIWindow
Parameters
Name Type Description
colorValue JSValue A hex color string (e.g. "#FF0000") or an HSColor object
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:234

rectangle() -> HSUIWindow

Add a rectangle shape
Declaration
rectangle() -> HSUIWindow
Returns
HSUIWindow
Self for chaining (apply modifiers like `fill()`, `frame()`)
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:240

circle() -> HSUIWindow

Add a circle shape
Declaration
circle() -> HSUIWindow
Returns
HSUIWindow
Self for chaining (apply modifiers like `fill()`, `frame()`)
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:244

text(content) -> HSUIWindow

Add a text element or an `HSString` object (from `hs.ui.string()`) for reactive text
Declaration
text(content) -> HSUIWindow
Parameters
Name Type Description
content JSValue The text to display — a plain JS string for static text,
Returns
HSUIWindow
Self for chaining (apply modifiers like `font()`, `foregroundColor()`)
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:250

image(imageValue) -> HSUIWindow

Add an image element
Declaration
image(imageValue) -> HSUIWindow
Parameters
Name Type Description
imageValue HSImage Image as HSImage object
Returns
HSUIWindow
Self for chaining (apply modifiers like `resizable()`, `aspectRatio()`, `frame()`)
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:255

video(videoValue) -> HSUIWindow

Add a video element Renders a SwiftUI `VideoPlayer` for the given `HSVideo`. Keep a reference to the `HSVideo` object to control playback (`play()`, `pause()`, `seek()`, `volume`) after the window is shown.
Declaration
video(videoValue) -> HSUIWindow
Parameters
Name Type Description
videoValue HSVideo Video as an HSVideo object
Returns
HSUIWindow
Self for chaining (apply modifiers like `frame()`, `opacity()`)
Example
const clip = HSVideo.fromURLs(["~/Movies/clip.mp4"])
hs.ui.window({x: 100, y: 100, w: 640, h: 360})
    .video(clip)
        .frame({w: 640, h: 360})
    .show()

clip.play()
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:275

button(label) -> HSUIWindow

Add a button element or an `HSString` object (from `hs.ui.string()`) for reactive text
Declaration
button(label) -> HSUIWindow
Parameters
Name Type Description
label JSValue The button label — a plain JS string for static text,
Returns
HSUIWindow
Self for chaining (apply `.fill()`, `.cornerRadius()`, `.font()`,
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:282

vstack() -> HSUIWindow

Begin a vertical stack (elements arranged top to bottom)
Declaration
vstack() -> HSUIWindow
Returns
HSUIWindow
Self for chaining (call `end()` when done)
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:288

hstack() -> HSUIWindow

Begin a horizontal stack (elements arranged left to right)
Declaration
hstack() -> HSUIWindow
Returns
HSUIWindow
Self for chaining (call `end()` when done)
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:292

zstack() -> HSUIWindow

Begin a z-stack (overlapping elements)
Declaration
zstack() -> HSUIWindow
Returns
HSUIWindow
Self for chaining (call `end()` when done)
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:296

spacer() -> HSUIWindow

Add flexible spacing that expands to fill available space
Declaration
spacer() -> HSUIWindow
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:300

webview(element) -> HSUIWindow

Embed a web browser element created with `hs.ui.webview()` (macOS 26+) The element fills the available space in the window layout. Keep a reference to the element to call navigation methods after the window is shown.
Declaration
webview(element) -> HSUIWindow
Parameters
Name Type Description
element UIWebView A `UIWebView` created via `hs.ui.webview()`
Returns
HSUIWindow
Self for chaining
Example
const wv = hs.ui.webview()
    .toolbar(["back", "forward", "reload", "url"])
    .loadURL("https://apple.com")

hs.ui.window({x: 100, y: 100, w: 1024, h: 768})
    .webview(wv)
    .show()
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:320

end() -> HSUIWindow

End the current layout container
Declaration
end() -> HSUIWindow
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:324

fill(colorValue) -> HSUIWindow

Fill a shape with a color
Declaration
fill(colorValue) -> HSUIWindow
Parameters
Name Type Description
colorValue JSValue A hex color string (e.g. "#FF0000") or an HSColor object
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:331

stroke(colorValue) -> HSUIWindow

Add a stroke (border) to a shape
Declaration
stroke(colorValue) -> HSUIWindow
Parameters
Name Type Description
colorValue JSValue A hex color string (e.g. "#FF0000") or an HSColor object
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:336

strokeWidth(width) -> HSUIWindow

Set the stroke width
Declaration
strokeWidth(width) -> HSUIWindow
Parameters
Name Type Description
width number Width in points
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:341

cornerRadius(radius) -> HSUIWindow

Round the corners of a shape
Declaration
cornerRadius(radius) -> HSUIWindow
Parameters
Name Type Description
radius number Corner radius in points
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:346

frame(dict) -> HSUIWindow

Set the frame (size) of an element
Declaration
frame(dict) -> HSUIWindow
Parameters
Name Type Description
dict {[key: string]: any} Dictionary with `w` and/or `h` (can be numbers or percentage strings like "50%")
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:351

opacity(value) -> HSUIWindow

Set the opacity of an element
Declaration
opacity(value) -> HSUIWindow
Parameters
Name Type Description
value number Opacity from 0.0 (transparent) to 1.0 (opaque)
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:356

font(font) -> HSUIWindow

Set the font for a text element
Declaration
font(font) -> HSUIWindow
Parameters
Name Type Description
font HSFont An HSFont object (e.g., `HSFont.title()`)
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:363

foregroundColor(colorValue) -> HSUIWindow

Set the text color
Declaration
foregroundColor(colorValue) -> HSUIWindow
Parameters
Name Type Description
colorValue JSValue A hex color string (e.g. "#FF0000") or an HSColor object
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:368

resizable() -> HSUIWindow

Make an image resizable (allows it to scale with frame size)
Declaration
resizable() -> HSUIWindow
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:374

aspectRatio(mode) -> HSUIWindow

Set the aspect ratio mode for an image
Declaration
aspectRatio(mode) -> HSUIWindow
Parameters
Name Type Description
mode string "fit" (scales to fit within frame) or "fill" (scales to fill frame)
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:379

padding(value) -> HSUIWindow

Add padding around a layout container
Declaration
padding(value) -> HSUIWindow
Parameters
Name Type Description
value number Padding in points
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:386

spacing(value) -> HSUIWindow

Set spacing between elements in a stack
Declaration
spacing(value) -> HSUIWindow
Parameters
Name Type Description
value number Spacing in points
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:391

onClick(callback) -> HSUIWindow

Set a callback to fire when the element is clicked
Declaration
onClick(callback) -> HSUIWindow
Parameters
Name Type Description
callback function A JavaScript function to call on click
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:398

onHover(callback) -> HSUIWindow

Set a callback to fire when the cursor enters or leaves the element
Declaration
onHover(callback) -> HSUIWindow
Parameters
Name Type Description
callback function A JavaScript function called with `true` when the cursor enters and `false` when it leaves
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:403