hammerspoon2-docs
    Preparing search index...

    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.

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

    Constructors

    constructor

    Methods

    allowResize aspectRatio backgroundColor button circle closable close cornerRadius end fill font foregroundColor frame hide hstack image level miniaturizable onClick onHover opacity padding rectangle resizable show spacer spacing stroke strokeWidth text titled vstack webview windowTitle zstack

    Constructors

    Methods

    • 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

    • 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

    • Set the window's background color

      Parameters

      • colorValue: HSColor

        Color as an HSColor object

      Returns HSUIWindow

      Self for chaining

    • 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(),

    • Add a circle shape

      Returns HSUIWindow

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

    • 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

    • Close and destroy the window

      Returns void

    • Round the corners of a shape

      Parameters

      • radius: number

        Corner radius in points

      Returns HSUIWindow

      Self for chaining

    • Set the font for a text element

      Parameters

      • font: HSFont

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

      Returns HSUIWindow

      Self for chaining

    • 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 the window (keeps it in memory)

      Returns void

    • Begin a horizontal stack (elements arranged left to right)

      Returns HSUIWindow

      Self for chaining (call end() when done)

    • Add an image element

      Parameters

      • imageValue: HSImage

        Image as HSImage object

      Returns HSUIWindow

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

    • 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

    • 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

    • 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

    • 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

    • Set the opacity of an element

      Parameters

      • value: number

        Opacity from 0.0 (transparent) to 1.0 (opaque)

      Returns HSUIWindow

      Self for chaining

    • Add padding around a layout container

      Parameters

      • value: number

        Padding in points

      Returns HSUIWindow

      Self for chaining

    • Add a rectangle shape

      Returns HSUIWindow

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

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

      Returns HSUIWindow

      Self for chaining

    • Add flexible spacing that expands to fill available space

      Returns HSUIWindow

      Self for chaining

    • Set spacing between elements in a stack

      Parameters

      • value: number

        Spacing in points

      Returns HSUIWindow

      Self for chaining

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

    • 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

    • Begin a vertical stack (elements arranged top to bottom)

      Returns HSUIWindow

      Self for chaining (call end() when done)

    • 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

    • 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

    • Begin a z-stack (overlapping elements)

      Returns HSUIWindow

      Self for chaining (call end() when done)

    Settings

    Member Visibility

    On This Page

    HSUIWindow
    Constructors
    Methods