hammerspoon2-docs
    Preparing search index...

    Class UIWebView

    hs.ui.webview

    A web browser element for embedding in hs.ui.window layouts* Available on macOS 26.0 or later, hs.ui.webview() creates a web browser element backed by a SwiftUI WebView and WebPage. Embed it in any hs.ui.window using .webview(element) — it fills the available space and can sit alongside other elements in stacks.

    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})
    .titled(true)
    .closable(true)
    .allowResize(true)
    .level("normal")
    .webview(wv)
    .show()

    Because wv is a regular JavaScript object you can keep a reference and call navigation

    wv.loadURL("https://google.com")
    wv.goBack()
    const wv = hs.ui.webview()
    .toolbar([
    "back", "forward", "reload", "url",
    {title: "Home", systemImage: "house", callback: () => wv.loadURL("https://apple.com")},
    {title: "Reload HS", callback: () => hs.reload()}
    ])
    .loadURL("https://apple.com")

    hs.ui.window({x: 100, y: 100, w: 1024, h: 768})
    .webview(wv)
    .show()
    const wv = hs.ui.webview()
    .toolbar(["back", "forward", "reload", "url"])
    .inspectable(true)
    .onNavigate((url) => console.log("Navigated to: " + url))
    .onTitleChange((title) => console.log("Title: " + title))
    .onLoadChange((loading, url, title, progress) => {
    if (!loading) console.log("Page ready: " + url)
    })
    .loadURL("https://apple.com")

    hs.ui.window({x: 100, y: 100, w: 1024, h: 768})
    .webview(wv)
    .show()
    const wv = hs.ui.webview()
    .toolbar(["back", "forward", "reload", "url"])
    .onNavigationDecision((url) => {
    return !url.includes("evil.com")
    })
    .loadURL("https://apple.com")

    hs.ui.window({x: 100, y: 100, w: 1024, h: 768})
    .webview(wv)
    .show()
    const wv = hs.ui.webview().loadURL("https://apple.com")
    hs.ui.window({x: 100, y: 100, w: 1024, h: 768}).webview(wv).show()

    // Fire and forget
    wv.execJS("document.body.style.backgroundColor = 'lightyellow'")

    // With result (note the JS method name is evalJSResult)
    wv.evalJSResult("document.title", (result, error) => {
    if (error) { console.log("Error: " + error) }
    else { console.log("Title: " + result) }
    })
    Index

    Constructors

    Properties

    canGoBack: boolean

    Whether the web view can navigate back in history

    canGoForward: boolean

    Whether the web view can navigate forward in history

    estimatedProgress: number

    The estimated loading progress from 0.0 to 1.0

    isLoading: boolean

    Whether the web view is currently loading a page

    title: string

    The title of the current page

    url: string | null

    The URL of the current page, or null if no page is loaded

    Methods

    • Enable or disable the macOS back/forward trackpad swipe gestures Gestures are enabled by default. Pass false to disable them.

      Parameters

      • enabled: boolean

        Pass false to disable back/forward swipe gestures

      Returns UIWebView

      Self for chaining

    • Control whether the web page background is visible Pass false to make the web view background transparent. Enabled (visible) by default.

      Parameters

      • visible: boolean

        Pass false to hide the web content background

      Returns UIWebView

      Self for chaining

    • Execute JavaScript in the web page and deliver the result to a callback The JavaScript method name is evalJSResult — it derives from the internal Objective-C selector evalJS:result:.

      Parameters

      • script: string

        The JavaScript expression to evaluate

      • callback: (result: any, error: string | null) => void

        Called with the result or an error message

      Returns UIWebView

      Self for chaining

    • Execute JavaScript in the web page without capturing the result

      Parameters

      • script: string

        The JavaScript code to execute

      Returns UIWebView

      Self for chaining

    • Navigate back in the browser history

      Returns UIWebView

      Self for chaining

    • Navigate forward in the browser history

      Returns UIWebView

      Self for chaining

    • Enable or disable the Safari Web Inspector for this web view When enabled, the web view appears in Safari → Develop menu.

      Parameters

      • value: boolean

        Pass true to enable the Web Inspector

      Returns UIWebView

      Self for chaining

    • Enable or disable link preview popovers shown on force-click Link previews are enabled by default. Pass false to disable them.

      Parameters

      • enabled: boolean

        Pass false to disable link previews

      Returns UIWebView

      Self for chaining

    • Load an HTML string directly into the web view

      Parameters

      • html: string

        The HTML content to display

      Returns UIWebView

      Self for chaining

    • Enable or disable the trackpad pinch-to-zoom magnification gesture The gesture is enabled by default. Pass false to disable it.

      Parameters

      • enabled: boolean

        Pass false to disable pinch-to-zoom

      Returns UIWebView

      Self for chaining

    • Register a callback that fires when loading state or progress changes Called whenever isLoading, url, title, or estimatedProgress changes.

      Parameters

      • callback: (
            isLoading: boolean,
            url: string | null,
            title: string,
            progress: number,
        ) => void

        Called with current loading state

      Returns UIWebView

      Self for chaining

    • Register a callback that fires when navigation to a new page completes

      Parameters

      • callback: (url: string) => void

        Called with the final URL

      Returns UIWebView

      Self for chaining

    • Register a callback that controls whether navigation is allowed Called before each navigation. Return true to allow or false to block.

      Parameters

      • callback: (url: string) => boolean

        Return true to allow, false to block

      Returns UIWebView

      Self for chaining

    • Register a callback that fires when the page title changes

      Parameters

      • callback: (title: string) => void

        Called with the new title

      Returns UIWebView

      Self for chaining

    • Configure the toolbar with a list of standard and custom items The toolbar renders above the web view. Each element of the array is either a string naming a standard control or a dictionary describing a custom button. An empty array (or omitting this call) hides the toolbar. Standard string items: "back", "forward", "reload", "url", "spacer".

      Parameters

      • items: (string | { callback: () => void; systemImage?: string; title?: string })[]

        Toolbar items in display order

      Returns UIWebView

      Self for chaining

      The toolbar will not be shown if the web view is in a borderless window

    • Set a custom User-Agent string for HTTP requests

      Parameters

      • ua: string

        The User-Agent string

      Returns UIWebView

      Self for chaining