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.

Building UI Elements

  • Shapes: rectangle(), circle()
  • Text: text(content)
  • Buttons: button(label) — uses SwiftUI's native Button for press-state feedback
  • Images: image(imageValue)
  • 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:73

hide() -> None

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

close() -> None

Close and destroy the window
Declaration
close() -> None
Returns
None
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:79

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:99

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:112

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:125

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:138

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:151

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:171

backgroundColor(colorValue) -> HSUIWindow

Set the window's background color
Declaration
backgroundColor(colorValue) -> HSUIWindow
Parameters
Name Type Description
colorValue HSColor Color as an HSColor object
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:176

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:182

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:186

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:192

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:197

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:204

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:210

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:214

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:218

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:222

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:242

end() -> HSUIWindow

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

fill(colorValue) -> HSUIWindow

Fill a shape with a color
Declaration
fill(colorValue) -> HSUIWindow
Parameters
Name Type Description
colorValue HSColor Color as an HSColor
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:253

stroke(colorValue) -> HSUIWindow

Add a stroke (border) to a shape
Declaration
stroke(colorValue) -> HSUIWindow
Parameters
Name Type Description
colorValue HSColor Color as an HSColor
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:258

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:263

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:268

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:273

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:278

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:285

foregroundColor(colorValue) -> HSUIWindow

Set the text color
Declaration
foregroundColor(colorValue) -> HSUIWindow
Parameters
Name Type Description
colorValue HSColor Color as HSColor
Returns
HSUIWindow
Self for chaining
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:290

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:296

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:301

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:308

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:313

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:320

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:325