WebView.constructor

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 will wait for it to complete first.

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

• width?: number

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

• 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 will wait 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

  • modifiers?: Modifier[]

    Modifier keys to hold during the keypress.

• 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 lets you pass 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'