> ## Documentation Index > Fetch the complete documentation index at: https://webview.js.org/llms.txt > Use this file to discover all available pages before exploring further. # Types Reference — Interfaces, Enums, and Event Payloads > Complete reference for shared TypeScript interfaces, enums, and event payload types used across the WebviewJS API: Dimensions, Monitor, CursorType. This page documents every shared TypeScript interface, enum, and event payload type used across the WebviewJS API. Import them alongside the classes you need: ```ts theme={null} import { Application, type Dimensions, type Monitor, type WebviewCookie, Theme, CursorType, ProgressBarState, } from '@webviewjs/webview'; ``` *** ## Geometry types These interfaces describe sizes, positions, and rectangular regions in logical or physical pixels. The API documentation for each method that uses these types specifies which coordinate space applies. ```ts theme={null} /** Width and height in pixels. */ interface Dimensions { width: number; height: number; } /** A two-dimensional point. */ interface Position { x: number; y: number; } /** * Logical-pixel rectangle used by child-webview positioning. * Coordinates are relative to the parent window's top-left corner. */ interface WebviewBounds { x: number; y: number; width: number; height: number; } ``` *** ## Cookie `WebviewCookie` represents a cookie stored in a webview's session. Pass it to `webview.setCookie()` or receive it from `webview.getCookies()`. ```ts theme={null} interface WebviewCookie { name: string; value: string; domain?: string; path?: string; httpOnly?: boolean; secure?: boolean; /** `"strict"`, `"lax"`, or `"none"`. */ sameSite?: 'strict' | 'lax' | 'none'; } ``` | Field | Type | Description | | ---------- | --------- | --------------------------------------------------------------- | | `name` | `string` | Cookie name. | | `value` | `string` | Cookie value. | | `domain` | `string` | Domain the cookie is scoped to. Omit to match the current host. | | `path` | `string` | URL path prefix the cookie is scoped to. Defaults to `"/"`. | | `httpOnly` | `boolean` | When `true`, the cookie is inaccessible to page JavaScript. | | `secure` | `boolean` | When `true`, the cookie is only sent over HTTPS. | | `sameSite` | `string` | Cross-site cookie policy: `"strict"`, `"lax"`, or `"none"`. | *** ## HTTP types ### `HeaderData` A key-value pair used in request and response headers throughout the custom protocol API. ```ts theme={null} interface HeaderData { key: string; value?: string; } ``` ### `CustomProtocolResponse` The return type for legacy custom-protocol handlers registered with `win.registerProtocol()`. You can also return a standard Fetch API `Response` object. ```ts theme={null} interface CustomProtocolResponse { /** Response body bytes. Required. */ body: Buffer; /** MIME type, e.g. `"text/html"`. Defaults to `"application/octet-stream"`. */ mimeType?: string; /** HTTP status code. Defaults to `200`. */ statusCode?: number; /** Extra response headers. */ headers?: HeaderData[]; } ``` *** ## Monitor `Monitor` describes a connected display as reported by the operating system. Retrieve monitors with `win.getAvailableMonitors()`, `win.getCurrentMonitor()`, or `win.getPrimaryMonitor()`. ```ts theme={null} interface Monitor { /** Display name, if the OS provides one. */ name?: string; /** DPI scale factor (e.g. `2` for a Retina / HiDPI display). */ scaleFactor: number; /** Physical resolution in pixels. */ size: Dimensions; /** Position of the monitor's top-left corner in the virtual desktop space. */ position: Position; /** All video modes supported by this monitor. */ videoModes: VideoMode[]; } ``` `VideoMode` describes a single display configuration available for the monitor, useful when entering exclusive fullscreen: ```ts theme={null} interface VideoMode { /** Resolution in pixels. */ size: Dimensions; /** Colour bit depth (e.g. `32`). */ bitDepth: number; /** Refresh rate in millihertz (e.g. `60000` for 60 Hz). */ refreshRate: number; } ``` *** ## IPC `IpcMessage` is the object received by `webview.onIpcMessage()` whenever page JavaScript calls `window.ipc.postMessage()`. ```ts theme={null} interface IpcMessage { /** Raw bytes of the message body. */ body: Buffer; /** HTTP-style method string (typically `"POST"`). */ method: string; /** Request headers forwarded by the IPC bridge. */ headers: HeaderData[]; /** The IPC endpoint URI. */ uri: string; } ``` *** ## Application events ### `ApplicationEvent` The payload type for all events emitted by `app.on(...)`. ```ts theme={null} interface ApplicationEvent { event: WebviewApplicationEvent; customMenuEvent?: CustomMenuEvent; } ``` `customMenuEvent` is only present when `event === WebviewApplicationEvent.CustomMenuClick`. ### `CustomMenuEvent` ```ts theme={null} interface CustomMenuEvent { /** The `id` of the `MenuItemOptions` that was clicked. */ id: string; /** Numeric ID of the window the click originated from. */ windowId: number; } ``` *** ## Enums ### `WebviewApplicationEvent` Discriminates the `event` field of every `ApplicationEvent` payload delivered to `app.on(...)` listeners. ```ts theme={null} enum WebviewApplicationEvent { WindowCloseRequested = 0, ApplicationCloseRequested = 1, CustomMenuClick = 2, Ready = 3, } ``` | Value | Description | | --------------------------- | ----------------------------------------------------------------------------------------- | | `WindowCloseRequested` | The user or OS requested that a window be closed. | | `ApplicationCloseRequested` | The last window closed or the OS requested the app quit. | | `CustomMenuClick` | A menu item with an `id` was clicked. The `customMenuEvent` field is populated. | | `Ready` | The application event loop started and the app is ready to create windows and tray icons. | *** ### `Theme` Controls or reports the colour scheme of a window or webview. ```ts theme={null} enum Theme { Light = 0, Dark = 1, System = 2, } ``` ### `FullscreenType` Passed to `win.setFullscreen()` to choose the fullscreen strategy. ```ts theme={null} enum FullscreenType { /** Full exclusive fullscreen — takes over the display entirely. */ Exclusive = 0, /** Borderless window fullscreen — maximises without a true mode change. */ Borderless = 1, } ``` ### `ProgressBarState` Passed inside a `JsProgressBar` object to `win.setProgressBar()` to update the taskbar progress indicator. ```ts theme={null} enum ProgressBarState { None = 0, Normal = 1, Indeterminate = 2, Paused = 3, Error = 4, } ``` | Value | Description | | --------------- | ------------------------------------------------------------------- | | `None` | Hide the progress indicator. | | `Normal` | Show a standard progress bar. Pair with a `progress` value (0–100). | | `Indeterminate` | Show an animated spinner / marquee (progress unknown). | | `Paused` | Show the bar in a paused / yellow state (Windows). | | `Error` | Show the bar in an error / red state (Windows). | ### `CursorType` Pass a `CursorType` value to `win.setCursor()` to change the mouse cursor shape over the window. | Value | Enum int | CSS equivalent | | -------------------------- | :------: | --------------- | | `Default` | 0 | `default` | | `Crosshair` | 1 | `crosshair` | | `Hand` | 2 | `pointer` | | `Arrow` | 3 | `default` | | `Move` | 4 | `move` | | `Text` | 5 | `text` | | `Wait` | 6 | `wait` | | `Help` | 7 | `help` | | `Progress` | 8 | `progress` | | `NotAllowed` | 9 | `not-allowed` | | `ContextMenu` | 10 | `context-menu` | | `Cell` | 11 | `cell` | | `VerticalText` | 12 | `vertical-text` | | `Alias` | 13 | `alias` | | `Copy` | 14 | `copy` | | `NoDrop` | 15 | `no-drop` | | `Grab` | 16 | `grab` | | `Grabbing` | 17 | `grabbing` | | `ZoomIn` | 18 | `zoom-in` | | `ZoomOut` | 19 | `zoom-out` | | `ResizeEast` | 20 | `e-resize` | | `ResizeNorth` | 21 | `n-resize` | | `ResizeNorthEast` | 22 | `ne-resize` | | `ResizeNorthWest` | 23 | `nw-resize` | | `ResizeSouth` | 24 | `s-resize` | | `ResizeSouthEast` | 25 | `se-resize` | | `ResizeSouthWest` | 26 | `sw-resize` | | `ResizeWest` | 27 | `w-resize` | | `ResizeEastWest` | 28 | `ew-resize` | | `ResizeNorthSouth` | 29 | `ns-resize` | | `ResizeNorthEastSouthWest` | 30 | `nesw-resize` | | `ResizeNorthWestSouthEast` | 31 | `nwse-resize` | | `ResizeColumn` | 32 | `col-resize` | | `ResizeRow` | 33 | `row-resize` | | `AllScroll` | 34 | `all-scroll` | *** ## Window event types `BrowserWindowEventMap` maps event name strings to their typed payload interfaces. Register listeners with `win.on(eventName, handler)`. | Event name | Payload fields | Description | | ---------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | | `move` | `x`, `y` (physical px) | The window's outer position changed. | | `resize` | `width`, `height` (physical px) | The window's inner (client) size changed. | | `close` | — | The window closed. | | `focus` | — | The window gained keyboard focus. | | `blur` | — | The window lost keyboard focus. | | `mouse-enter` | `x`, `y` (physical px) | The cursor entered the window area. | | `mouse-leave` | — | The cursor left the window area. | | `mouse-move` | `x`, `y` (physical px) | The cursor moved within the window. | | `mouse-down` | `x`, `y`, `button` (0=left, 1=middle, 2=right), `modifiers?` | A mouse button was pressed. | | `mouse-up` | `x`, `y`, `button`, `modifiers?` | A mouse button was released. | | `scroll` | `deltaX`, `deltaY` (physical px) | The scroll wheel moved. | | `key-down` | `key?`, `code?`, `modifiers?`, `isRepeat?` | A keyboard key was pressed. `modifiers` bitmask: 1=Shift, 2=Ctrl, 4=Alt, 8=Meta. | | `key-up` | `key?`, `code?`, `modifiers?` | A keyboard key was released. | | `file-drop` | `files?` (string\[]) | Files were dropped onto the window. | | `file-hover` | `files?` (string\[]) | Files are being dragged over the window. | | `file-hover-cancelled` | — | A file-drag operation was cancelled without dropping. | | `scale-factor-changed` | `scaleFactor` | The window moved to a display with a different DPI scale factor. | | `theme-changed` | `text: 'light' \| 'dark'` | The OS colour scheme changed. | | `ime` | `text?`, `phase` | An IME (Input Method Editor) state change. `phase`: `enabled`, `preedit`, `commit`, `disabled`. | | `touch` | `x`, `y`, `touchId`, `phase` | A touch event. `phase`: `started`, `moved`, `ended`, `cancelled`. | *** ## Webview event types `WebviewEventMap` maps webview event names to their typed payloads. Register listeners with `webview.on(eventName, handler)`. | Event name | Payload fields | Description | | -------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page-load-started` | `event`, `url?` | Navigation began and the page started loading. | | `page-load-finished` | `event`, `url?` | The page finished loading. | | `title-changed` | `event`, `title?` | The document `` changed. | | `download-started` | `event`, `url?` | A file download began. | | `download-completed` | `event`, `url?`, `success?` | A file download finished. `success` is `true` on success, `false` on failure. | | `navigation` | `event`, `url?` | Fired for every navigation attempt, regardless of the `navigationHandler` result. | | `new-window` | `event`, `url?` | The page requested a new window (`window.open`, `target="_blank"`, etc.). **On Windows this event is observational** — it fires from a separate WebView2 thread and cannot cancel the navigation. | *** ## Application event types `ApplicationEventMap` maps application event names to their payloads. Register listeners with `app.on(eventName, handler)`. | Event name | When it fires | | ----------------------------- | --------------------------------------------------------------------------------------------------------------- | | `window-close-requested` | The user (or OS) requested that a window be closed. You can intercept this to show a save dialog. | | `application-close-requested` | The last window was closed or the OS requested the app quit. Call `app.exit()` to confirm. | | `custom-menu-click` | A menu item with an `id` was clicked. The payload includes `customMenuEvent.id` and `customMenuEvent.windowId`. | | `ready` | The application event loop is running and the app is ready to create windows and tray icons. | *** ## SerializationError `SerializationError` is a subclass of `Error` with `name === "SerializationError"`. The `webview.expose()` helper uses JSON serialization for all static values, function arguments, and return values. If you pass or return a value that cannot be serialized to JSON (such as a `Map`, a `Set`, a `Symbol`, a `BigInt`, a circular reference, or an `undefined` property), `expose()` or the proxied function call rejects with a `SerializationError`. ```ts theme={null} class SerializationError extends Error { name: 'SerializationError'; } ``` ```js theme={null} import { SerializationError } from '@webviewjs/webview'; webview.expose('api', { getData: () => ({ items: [1, 2, 3], // ✓ serializable map: new Map([['a', 1]]), // ✗ throws SerializationError }), }); // In an async context you can catch it: try { await page.api.getData(); } catch (err) { if (err.name === 'SerializationError') { console.error('Return value could not be serialized'); } } ``` *** ## WebContextOptions `WebContextOptions` is passed to `app.createWebContext()` to configure an isolated browsing context for one or more webviews. Webviews that share a `WebContext` also share their cookie store and cache. ```ts theme={null} interface WebContextOptions { /** * Custom directory for storing WebView data (cookies, cache, IndexedDB, etc.). * Useful on Windows where a bundled application cannot write to Program Files. */ dataDirectory?: string; /** * Allow browser-automation tools (e.g. WebDriver) to control webviews * created in this context. * Currently enforced on Linux only; at most one context may allow automation * at a time. */ allowsAutomation?: boolean; } ``` ```js theme={null} const ctx = app.createWebContext({ dataDirectory: '/home/user/.config/myapp/webdata', allowsAutomation: false, }); const win = app.createBrowserWindow(); const webview = win.createWebview({ url: 'app://localhost/' }, ctx); ``` See the [WebContext reference](/api/web-context) for full details on context sharing and disposal.