Class HSUIWindow

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

Modifying Elements

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();

Constructors

constructor

new HSUIWindow(): HSUIWindow
Returns HSUIWindow

Methods

allowResize

allowResize(enable: boolean): HSUIWindow
Allow or prevent the user from resizing the window Enabled by default. Only has a visual effect when .titled(true) is also set.
Parameters
- enable: boolean
  Pass false to prevent the user from resizing the window
Returns HSUIWindow
Self for chaining

aspectRatio

aspectRatio(mode: string): HSUIWindow
Set the aspect ratio mode for an image
Parameters
- mode: string
  "fit" (scales to fit within frame) or "fill" (scales to fill frame)
Returns HSUIWindow
Self for chaining

backgroundColor

backgroundColor(colorValue: string | HSColor): HSUIWindow
Set the window's background color
Parameters
- colorValue: string | HSColor
  A hex color string (e.g. "#FF0000") or an HSColor object
Returns HSUIWindow
Self for chaining

button

button(label: string | HSString): HSUIWindow
Add a button element or an HSString object (from hs.ui.string()) for reactive text
Parameters
- label: string | HSString
  The button label — a plain JS string for static text,
Returns HSUIWindow
Self for chaining (apply .fill(), .cornerRadius(), .font(),

circle

circle(): HSUIWindow
Add a circle shape

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

closable

closable(show: boolean): HSUIWindow
Show or hide the close button on the window Requires .titled(true) to be visible. Enabled by default.
Parameters
- show: boolean
  Pass false to hide the close button
Returns HSUIWindow
Self for chaining

cornerRadius

cornerRadius(radius: number): HSUIWindow
Round the corners of a shape
Parameters
- radius: number
  Corner radius in points
Returns HSUIWindow
Self for chaining

destroy

destroy(): void
Destroy the window

Returns void

end

end(): HSUIWindow
End the current layout container

Returns HSUIWindow
Self for chaining

fill

fill(colorValue: string | HSColor): HSUIWindow
Fill a shape with a color
Parameters
- colorValue: string | HSColor
  A hex color string (e.g. "#FF0000") or an HSColor object
Returns HSUIWindow
Self for chaining

font

font(font: HSFont): HSUIWindow
Set the font for a text element
Parameters
- font: HSFont
  An HSFont object (e.g., HSFont.title())
Returns HSUIWindow
Self for chaining

foregroundColor

foregroundColor(colorValue: string | HSColor): HSUIWindow
Set the text color
Parameters
- colorValue: string | HSColor
  A hex color string (e.g. "#FF0000") or an HSColor object
Returns HSUIWindow
Self for chaining

frame

frame(dict: Record<string, any>): HSUIWindow
Set the frame (size) of an element
Parameters
- dict: Record<string, any>
  Dictionary with w and/or h (can be numbers or percentage strings like "50%")
Returns HSUIWindow
Self for chaining

hide

hide(): void
Hide the window (keeps it in memory)

Returns void

hstack

hstack(): HSUIWindow
Begin a horizontal stack (elements arranged left to right)

Returns HSUIWindow
Self for chaining (call end() when done)

image

image(imageValue: HSImage): HSUIWindow
Add an image element
Parameters
- imageValue: HSImage
  Image as HSImage object
Returns HSUIWindow
Self for chaining (apply modifiers like resizable(), aspectRatio(), frame())

level

level(
    name:
        | "\"normal\""
        | "\"floating\""
        | "\"screenSaver\""
        | "\"dock\""
        | "\"status\""
        | "\"popUpMenu\"",
): HSUIWindow
Set the window stacking level Controls where this window sits in the macOS window hierarchy.
Parameters
- name:
      | "\"normal\""
      | "\"floating\""
      | "\"screenSaver\""
      | "\"dock\""
      | "\"status\""
      | "\"popUpMenu\""
  The level name
Returns HSUIWindow
Self for chaining

miniaturizable

miniaturizable(show: boolean): HSUIWindow
Show or hide the miniaturize (yellow) button on the window Requires .titled(true) to be visible. Enabled by default.
Parameters
- show: boolean
  Pass false to hide the miniaturize button
Returns HSUIWindow
Self for chaining

onClick

onClick(callback: () => void): HSUIWindow
Set a callback to fire when the element is clicked
Parameters
- callback: () => void
  A JavaScript function to call on click
Returns HSUIWindow
Self for chaining

onDestroy

onDestroy(callback: () => void): 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.
Parameters
- callback: () => void
  A JavaScript function called after the window is destroyed
Returns HSUIWindow
Self for chaining

onHide

onHide(callback: () => void): 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.
Parameters
- callback: () => void
  A JavaScript function called after the window is hidden
Returns HSUIWindow
Self for chaining

onHover

onHover(callback: (isHovering: boolean) => void): HSUIWindow
Set a callback to fire when the cursor enters or leaves the element
Parameters
- callback: (isHovering: boolean) => void
  A JavaScript function called with true when the cursor enters and false when it leaves
Returns HSUIWindow
Self for chaining

onShow

onShow(callback: () => void): HSUIWindow
Set a callback to fire after the window is shown
Parameters
- callback: () => void
  A JavaScript function called after the window becomes visible
Returns HSUIWindow
Self for chaining

opacity

opacity(value: number): HSUIWindow
Set the opacity of an element
Parameters
- value: number
  Opacity from 0.0 (transparent) to 1.0 (opaque)
Returns HSUIWindow
Self for chaining

padding

padding(value: number): HSUIWindow
Add padding around a layout container
Parameters
- value: number
  Padding in points
Returns HSUIWindow
Self for chaining

rectangle

rectangle(): HSUIWindow
Add a rectangle shape

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

resizable

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

Returns HSUIWindow
Self for chaining

show

show(): HSUIWindow
Show the window

Returns HSUIWindow
Self for chaining

spacer

spacer(): HSUIWindow
Add flexible spacing that expands to fill available space

Returns HSUIWindow
Self for chaining

spacing

spacing(value: number): HSUIWindow
Set spacing between elements in a stack
Parameters
- value: number
  Spacing in points
Returns HSUIWindow
Self for chaining

stroke

stroke(colorValue: string | HSColor): HSUIWindow
Add a stroke (border) to a shape
Parameters
- colorValue: string | HSColor
  A hex color string (e.g. "#FF0000") or an HSColor object
Returns HSUIWindow
Self for chaining

strokeWidth

strokeWidth(width: number): HSUIWindow
Set the stroke width
Parameters
- width: number
  Width in points
Returns HSUIWindow
Self for chaining

text

text(content: string | HSString): HSUIWindow
Add a text element or an HSString object (from hs.ui.string()) for reactive text
Parameters
- content: string | HSString
  The text to display — a plain JS string for static text,
Returns HSUIWindow
Self for chaining (apply modifiers like font(), foregroundColor())

titled

titled(show: boolean): 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.
Parameters
- show: boolean
  Pass false to make the window borderless
Returns HSUIWindow
Self for chaining

video

video(videoValue: HSVideo): 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.
Parameters
- videoValue: HSVideo
  Video as an HSVideo object
Returns HSUIWindow
Self for chaining (apply modifiers like frame(), opacity())

vstack

vstack(): HSUIWindow
Begin a vertical stack (elements arranged top to bottom)

Returns HSUIWindow
Self for chaining (call end() when done)

webview

webview(element: UIWebView): 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.
Parameters
- element: UIWebView
  A UIWebView created via hs.ui.webview()
Returns HSUIWindow
Self for chaining

windowTitle

windowTitle(text: string): HSUIWindow
Set the text shown in the window's title bar Only visible when .titled(true) is set (the default).
Parameters
- text: string
  The title bar text
Returns HSUIWindow
Self for chaining

zstack

zstack(): HSUIWindow
Begin a z-stack (overlapping elements)

Returns HSUIWindow
Self for chaining (call end() when done)

Class HSUIWindow

HSUIWindow

Building UI Elements

Modifying Elements

Examples

Index

Constructors

Methods

Constructors

constructor

Returns HSUIWindow

Methods

allowResize

Parameters

Returns HSUIWindow

aspectRatio

Parameters

Returns HSUIWindow

backgroundColor

Parameters

Returns HSUIWindow

button

Parameters

Returns HSUIWindow

circle

Returns HSUIWindow

closable

Parameters

Returns HSUIWindow

cornerRadius

Parameters

Returns HSUIWindow

destroy

Returns void

end

Returns HSUIWindow

fill

Parameters

Returns HSUIWindow

font

Parameters

Returns HSUIWindow

foregroundColor

Parameters

Returns HSUIWindow

frame

Parameters

Returns HSUIWindow

hide

Returns void

hstack

Returns HSUIWindow

image

Parameters

Returns HSUIWindow

level

Parameters

Returns HSUIWindow

miniaturizable

Parameters

Returns HSUIWindow

onClick

Parameters

Returns HSUIWindow

onDestroy

Parameters

Returns HSUIWindow

onHide

Parameters

Returns HSUIWindow

onHover

Parameters

Returns HSUIWindow

onShow

Parameters

Returns HSUIWindow

opacity

Parameters

Returns HSUIWindow

padding