namespace

WebView

namespace WebView

  • interface ClickOptions

    • button?: 'left' | 'right' | 'middle'
    • clickCount?: 2 | 1 | 3

      Number of clicks (1 = single, 2 = double, 3 = triple).

    • modifiers?: Modifier[]

      Modifier keys to hold during the click.

  • interface ClickSelectorOptions

    • button?: 'left' | 'right' | 'middle'
    • clickCount?: 2 | 1 | 3

      Number of clicks (1 = single, 2 = double, 3 = triple).

    • modifiers?: Modifier[]

      Modifier keys to hold during the click.

    • timeout?: number

      Maximum time in milliseconds to wait for the element to become actionable (attached, visible, stable for 2 frames, not obscured).

  • interface ConstructorOptions

    • backend?: Backend

      Browser backend. Defaults to "webkit" on macOS, throws on other platforms unless "chrome" is specified.

    • console?: ConsoleCapture

      Capture page-side console.* calls. See ConsoleCapture.

    • dataStore?: 'ephemeral' | { directory: string }

      Storage backing for cookies, localStorage, IndexedDB, etc.

      • "ephemeral" (default): in-memory only, nothing written to disk.
      • { directory }: persistent storage rooted at the given path. Multiple views with the same directory share state.

      Chrome backend: directory is per-Chrome-process (--user-data-dir), not per-view. The first view's directory applies to all views spawned in the same Bun process.

    • headless?: boolean

      Only true (headless) is implemented.

    • height?: number

      Viewport height in pixels. Range: [1, 16384].

    • url?: string

      Initial URL to navigate to. The navigation starts before the constructor returns; await view.navigate(otherUrl) or any other operation waits for it to complete first.

      Equivalent to calling view.navigate(url) immediately after construction.

    • width?: number

      Viewport width in pixels. Range: [1, 16384].

  • interface PressOptions

  • interface ScrollToOptions

    • block?: 'end' | 'center' | 'start' | 'nearest'

      Vertical alignment. "nearest" scrolls minimally (no-op if already in view); "center" snaps the element's center to the viewport center.

    • timeout?: number

      Maximum time in milliseconds to wait for the element to exist.

  • type Backend =
    | 'webkit'
    | 'chrome'
    | { type: 'chrome'; url: string }
    | { argv: string[]; path: string; stderr: 'inherit' | 'ignore'; stdout: 'inherit' | 'ignore'; type: 'chrome'; url: false }
    | { stderr: 'inherit' | 'ignore'; stdout: 'inherit' | 'ignore'; type: 'webkit' }

    Browser backend selection.

    • "webkit" (default): WKWebView. macOS only. Zero external dependencies — uses the system WebKit.framework.
    • "chrome": Chrome/Chromium via DevTools Protocol over --remote-debugging-pipe. Works anywhere Chrome is installed. Auto-detects the binary in standard locations; override with backend.path or the BUN_CHROME_PATH environment variable.

    The object form accepts extra launch flags. Chrome switches are last-wins for duplicates, so argv can override the defaults.

    Chrome is spawned once per process — the first new Bun.WebView() call's path/argv/dataStore.directory win; subsequent views reuse the same Chrome instance via Target.createTarget.

    Default flags: --remote-debugging-pipe --headless --no-first-run --no-default-browser-check --disable-gpu --user-data-dir=<temp>.

  • type ConsoleCapture = typeof console | (type: string, ...args: unknown[]) => void

    Console capture. Called for each console.* invocation in the page.

    • globalThis.console: forward directly to the parent's console. console.log("hi") in the page prints hi to stdout with Bun's formatter; console.error goes to stderr. Zero JS overhead per call — dispatches through ConsoleClient directly.
    • (type, ...args) => void: custom callback. type is the method name ("log" | "warn" | "error" | "info" | "debug" | ...). Primitive args unwrap to their raw values; object args arrive as a structured descriptor — for Chrome, the CDP RemoteObject with .type/.className/.description/.preview.properties; for WebKit, the JSON round-trip of the object (lossy for functions/ circular refs, which stringify to their String(...) coercion).
  • type Modifier =
    | 'Shift'
    | 'Control'
    | 'Alt'
    | 'Meta'
  • type VirtualKey =
    | 'Enter'
    | 'Tab'
    | 'Space'
    | 'Backspace'
    | 'Delete'
    | 'Escape'
    | 'ArrowLeft'
    | 'ArrowRight'
    | 'ArrowUp'
    | 'ArrowDown'
    | 'Home'
    | 'End'
    | 'PageUp'
    | 'PageDown'