HSUIWindow

Type

HSUIWindow

A custom window with declarative UI building

HSUIWindow allows you to create custom borderless 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()

Show the window

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:73

Parameters

None

Returns

HSUIWindow - Self for chaining

hide()

Hide the window (keeps it in memory)

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:76

Parameters

None

Returns

Nothing

close()

Close and destroy the window

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:79

Parameters

None

Returns

Nothing

backgroundColor(colorValue)

Set the window's background color

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:86

Parameters

  • colorValue JSValue

    Color as hex string (e.g., "#FF0000") or HSColor object

Returns

HSUIWindow - Self for chaining

rectangle()

Add a rectangle shape

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:92

Parameters

None

Returns

HSUIWindow - Self for chaining (apply modifiers like `fill()`, `frame()`)

circle()

Add a circle shape

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:96

Parameters

None

Returns

HSUIWindow - Self for chaining (apply modifiers like `fill()`, `frame()`)

text(content)

Add a text element or an `HSString` object (from `hs.ui.string()`) for reactive text

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:102

Parameters

  • content JSValue

    The text to display — a plain JS string for static text,

Returns

HSUIWindow - Self for chaining (apply modifiers like `font()`, `foregroundColor()`)

image(imageValue)

Add an image element

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:107

Parameters

  • imageValue JSValue

    Image as HSImage object or file path string

Returns

HSUIWindow - Self for chaining (apply modifiers like `resizable()`, `aspectRatio()`, `frame()`)

button(label)

Add a button element or an `HSString` object (from `hs.ui.string()`) for reactive text

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:114

Parameters

  • label JSValue

    The button label — a plain JS string for static text,

Returns

HSUIWindow - Self for chaining (apply `.fill()`, `.cornerRadius()`, `.font()`,

vstack()

Begin a vertical stack (elements arranged top to bottom)

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:120

Parameters

None

Returns

HSUIWindow - Self for chaining (call `end()` when done)

hstack()

Begin a horizontal stack (elements arranged left to right)

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:124

Parameters

None

Returns

HSUIWindow - Self for chaining (call `end()` when done)

zstack()

Begin a z-stack (overlapping elements)

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:128

Parameters

None

Returns

HSUIWindow - Self for chaining (call `end()` when done)

spacer()

Add flexible spacing that expands to fill available space

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:132

Parameters

None

Returns

HSUIWindow - Self for chaining

end()

End the current layout container

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:136

Parameters

None

Returns

HSUIWindow - Self for chaining

fill(colorValue)

Fill a shape with a color

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:143

Parameters

  • colorValue JSValue

    Color as hex string or HSColor

Returns

HSUIWindow - Self for chaining

stroke(colorValue)

Add a stroke (border) to a shape

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:148

Parameters

  • colorValue JSValue

    Color as hex string or HSColor

Returns

HSUIWindow - Self for chaining

strokeWidth(width)

Set the stroke width

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:153

Parameters

  • width number

    Width in points

Returns

HSUIWindow - Self for chaining

cornerRadius(radius)

Round the corners of a shape

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:158

Parameters

  • radius number

    Corner radius in points

Returns

HSUIWindow - Self for chaining

frame(dict)

Set the frame (size) of an element

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:163

Parameters

  • dict {[key: string]: any}

    Dictionary with `w` and/or `h` (can be numbers or percentage strings like "50%")

Returns

HSUIWindow - Self for chaining

opacity(value)

Set the opacity of an element

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:168

Parameters

  • value number

    Opacity from 0.0 (transparent) to 1.0 (opaque)

Returns

HSUIWindow - Self for chaining

font(font)

Set the font for a text element

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:175

Parameters

  • font HSFont

    An HSFont object (e.g., `HSFont.title()`)

Returns

HSUIWindow - Self for chaining

foregroundColor(colorValue)

Set the text color

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:180

Parameters

  • colorValue JSValue

    Color as hex string or HSColor

Returns

HSUIWindow - Self for chaining

resizable()

Make an image resizable (allows it to scale with frame size)

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:186

Parameters

None

Returns

HSUIWindow - Self for chaining

aspectRatio(mode)

Set the aspect ratio mode for an image

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:191

Parameters

  • mode string

    "fit" (scales to fit within frame) or "fill" (scales to fill frame)

Returns

HSUIWindow - Self for chaining

padding(value)

Add padding around a layout container

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:198

Parameters

  • value number

    Padding in points

Returns

HSUIWindow - Self for chaining

spacing(value)

Set spacing between elements in a stack

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:203

Parameters

  • value number

    Spacing in points

Returns

HSUIWindow - Self for chaining

onClick(callback)

Set a callback to fire when the element is clicked

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:210

Parameters

  • callback JSValue

    A JavaScript function to call on click

Returns

HSUIWindow - Self for chaining

onHover(callback)

Set a callback to fire when the cursor enters or leaves the element

Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:215

Parameters

  • callback JSValue

    A JavaScript function called with a boolean: true when entering, false when leaving

Returns

HSUIWindow - Self for chaining