Log inTry it free

Webviews

Embed web content inside one of your windows. Unlike Windows (native OS windows), a webview is a rectangle of web content layered over a host window — use it to wrap third-party pages (an OAuth screen, an in-app browser) in your own chrome (a back button, a URL bar) instead of navigating the window away.

Each webview lives inside exactly one host window, is identified by a webviewId, and can be positioned either at fixed pixel coordinates (bounds) or auto-filling the host window with insets (fill).

Embedded content is untrusted. The webview does NOT receive the Deskifier SDK and cannot call sensitive commands. Even when the host↔webview message channel is enabled, the webview gets no capability access — it can only send messages up to the host, which runs the actual logic.

Methods

Create Webview

Creates a webview inside a host window.

await window.deskifier.webviews.create({ arguments })

Arguments

  • hostWindowId String (Optional)
    The window to attach the webview to. Defaults to the calling window.
  • url String (Optional)
    Remote URL to load. Provide either url or html.
  • html String (Optional)
    Inline app-owned HTML (loaded via a data: URL) — no hosting needed. Provide either url or html.
  • bounds Deskifier.WebviewBounds (Optional)
    Fixed pixel rectangle inside the host window. Provide either bounds or fill.
  • fill Deskifier.WebviewInsets (Optional)
    Cover the host window inset by these edges — great for laying content "below a 40px bar". The webview auto-resizes with the window.
  • backgroundColor String (Optional)
    CSS color used for the webview background while its page loads.
  • messaging Boolean (Optional)
    Enable the host↔webview message channel (postMessage/onMessage). See the trust-model callout below before turning this on. Default is false.

Only enable messaging: true for content you trust to talk to your app (e.g. your own UI). A third-party page (like an OAuth screen) should be left off so it gets no bridge at all. Even with messaging on, the webview has no capability access — it can only message the host.

Returns

  • success Boolean
    If the action was successful.
  • message String
    Additional confirmation, or error details if action was unsuccessful.
  • webviewId String
    The ID of the new webview.

Example

const { webviewId } = await window.deskifier.webviews.create({
  url: 'https://accounts.google.com/o/oauth2/v2/auth?...',
  fill: { top: 40 },       // sits below your 40px header bar
  backgroundColor: '#ffffff',
});

console.log(webviewId); // "webview-1"

Load URL

Navigates the webview to a URL.

await window.deskifier.webviews.loadURL({ arguments })

Arguments

  • webviewId String (Required)
  • url String (Required)

Returns

  • success Boolean
  • message String

Go Back

Goes back one step in the webview's history. No-op if it can't.

await window.deskifier.webviews.goBack({ arguments })

Arguments

  • webviewId String (Required)

Returns

  • success Boolean
  • message String

Go Forward

Goes forward one step in the webview's history. No-op if it can't.

await window.deskifier.webviews.goForward({ arguments })

Arguments

  • webviewId String (Required)

Returns

  • success Boolean
  • message String

Reload

Reloads the webview's current page.

await window.deskifier.webviews.reload({ arguments })

Arguments

  • webviewId String (Required)

Returns

  • success Boolean
  • message String

Stop

Stops the current load.

await window.deskifier.webviews.stop({ arguments })

Arguments

  • webviewId String (Required)

Returns

  • success Boolean
  • message String

Layout

Set Bounds

Repositions or resizes a webview. Pass either bounds (fixed pixels) or fill (auto-resizing insets).

await window.deskifier.webviews.setBounds({ arguments })

Arguments

Returns

  • success Boolean
  • message String

Show Webview

Shows a webview without destroying it.

await window.deskifier.webviews.show({ arguments })

Arguments

  • webviewId String (Required)

Returns

  • success Boolean
  • message String

Hide Webview

Hides a webview without destroying it. Its state (loaded page, scroll position, history) is preserved.

await window.deskifier.webviews.hide({ arguments })

Arguments

  • webviewId String (Required)

Returns

  • success Boolean
  • message String

Cleanup

Destroy Webview

Destroys a webview and removes it from its host window.

await window.deskifier.webviews.destroy({ arguments })

Arguments

  • webviewId String (Required)

Returns

  • success Boolean
  • message String

Messaging

Host↔webview messaging is opt-in — the webview must have been created with messaging: true. See the trust-model note under Create Webview.

The channel is deliberately narrow: the webview can only broadcast events / publish state to your host page. Your host (which HAS the full SDK) decides what to do with them.

Post Message

Sends a message down to a webview's page. The webview receives it via window.deskifier.webview.onMessage inside its own runtime.

await window.deskifier.webviews.postMessage({ arguments })

Arguments

  • webviewId String (Required)
  • data Any (Required)
    Any JSON-serializable value.

Returns

  • success Boolean
  • message String

On Message

Receives messages a webview posts up (via window.deskifier.webview.postMessage inside the webview). Use msg.webviewId to tell which webview it came from. Returns an unsubscribe function.

const unsubscribe = window.deskifier.webviews.onMessage((msg) => {
  // msg.webviewId — which webview sent it
  // msg.data      — the message payload
});

Arguments (passed to your handler)

  • webviewId String
  • data Any

Returns

  • Unsubscribe Function
    Call to stop listening.

Events

On Event

Subscribe to navigation and lifecycle events for webviews. One handler receives events for every webview — filter by event.webviewId. Returns an unsubscribe function.

const unsubscribe = window.deskifier.webviews.onEvent((event) => {
  if (event.webviewId !== myWebviewId) return;
  if (event.type === 'did-navigate') {
    console.log('navigated to', event.url);
  }
});

Arguments (passed to your handler)

  • webviewId String
    Which webview fired the event.
  • type String
    One of did-navigate, did-fail-load, page-title-updated, loading.
  • url String (Optional)
    Populated on did-navigate and did-fail-load.
  • canGoBack Boolean (Optional)
    Populated on did-navigate — mirror this into your back-button's disabled state.
  • canGoForward Boolean (Optional)
    Populated on did-navigate.
  • title String (Optional)
    Populated on page-title-updated.
  • loading Boolean (Optional)
    Populated on loading — true when a load starts, false when it finishes.
  • code Number (Optional)
    Populated on did-fail-load — Chromium error code.
  • description String (Optional)
    Populated on did-fail-load — human-readable error description.

Returns

  • Unsubscribe Function
    Call to stop listening.

Objects

WebviewBounds

  • x Number
    X coordinate (pixels) inside the host window.
  • y Number
    Y coordinate (pixels) inside the host window.
  • width Number
    Width in pixels.
  • height Number
    Height in pixels.

WebviewInsets

All fields optional; each defaults to 0. The webview fills the host window inset by these edges and auto-resizes with the window.

  • top Number (Optional)
  • right Number (Optional)
  • bottom Number (Optional)
  • left Number (Optional)