Types and low-level exports

This page covers shared types and the exported values that are not methods of a single class. The Application, BrowserWindow, Webview, WebContext, TrayIcon, and Notification references describe each class's methods and events.

Geometry and monitorsCopy Anchor Link

interface Dimensions {
  width: number;
  height: number;
}
interface Position {
  x: number;
  y: number;
}
interface WebviewBounds {
  x: number;
  y: number;
  width: number;
  height: number;
}

interface Monitor {
  name?: string;
  scaleFactor: number;
  size: Dimensions;
  position: Position;
  videoModes: VideoMode[];
}
interface VideoMode {
  size: Dimensions;
  bitDepth: number;
  refreshRate: number;
}

Window sizes and monitor geometry use physical pixels unless a method accepts a logical argument. WebviewBounds uses logical pixels relative to the parent window.

Creation and configuration typesCopy Anchor Link

FileFilter has name: string and extensions: string[]. Its extensions contain suffixes such as ['txt', 'md'].

WebviewOptions.nativeFileDrop defaults to false. When enabled, the Webview's event map includes drag-enter, drag-over, drag-drop, and drag-leave; see Webview.

TrayIconImage has data: Buffer, with optional width and height. Pass encoded image bytes without dimensions or raw RGBA bytes with dimensions. If only width is supplied, the native decoder treats the image as square; height without width is invalid.

Protocol, cookie, and IPC dataCopy Anchor Link

interface HeaderData {
  key: string;
  value?: string;
}

interface WebviewCookie {
  name: string;
  value: string;
  domain?: string;
  path?: string;
  httpOnly?: boolean;
  secure?: boolean;
  sameSite?: string;
}

interface IpcMessage {
  body: Buffer;
  method: string;
  headers: HeaderData[];
  uri: string;
}

onIpcMessage() receives IpcMessage when page code calls window.ipc.postMessage(string). The body is a Buffer; the other fields describe the native request. See IPC messaging.

Custom protocol handlers registered by BrowserWindow.registerProtocol() use the Fetch API Request and may return a Fetch API Response. The legacy native response form is:

interface CustomProtocolResponse {
  body: Buffer;
  statusCode?: number; // default 200
  mimeType?: string; // default application/octet-stream
  headers?: HeaderData[];
}

CustomProtocolRequest is the older plain-object request shape retained in the generated binding declarations; it is not the argument passed to the current public protocol handler. ProtocolRequest and ExposeCallData describe lower- level native bridge payloads and are not needed by normal application code. NativeNotificationAction, NativeNotificationOptions, and NotificationEventPayload are also native-wrapper types; use the higher-level Notification and its NotificationOptions instead.

Event payloadsCopy Anchor Link

The classes expose typed event maps:

• ApplicationEventMap covers ready, window-close-requested, application-close-requested, and custom-menu-click.
• BrowserWindowEventMap maps window, pointer, keyboard, file-drop, scale, theme, IME, touch, and close events to their payload interfaces. The close payload provides synchronous preventDefault(); see Application lifecycle.
• WebviewEventMap maps load, title, download, navigation, and new-window events plus native file drag events to their payload interfaces. Observation events cannot cancel a request; see Webview.
• TrayEventMap maps click, double-click, enter, move, and leave to TrayEventPayload. Their availability depends on the platform.
• NotificationEventMap maps show, click, close, and error to NotificationEvent.

The exported payload types include ApplicationEvent, CustomMenuEvent, WindowEventPayload, WebviewEventPayload, WebviewNewWindowFeatures, WebviewWindowSize, WebviewWindowPosition, WebviewDragEvent, TrayEventPayload, TrayRect, AndroidContentRect, and the event-specific types exported from the package root. CustomMenuEvent contains id and windowId; the current native adapter sets windowId to 0 for menu events.

WebviewEventPayload includes optional paths: string[] and position: WebviewWindowPosition properties for native file-drag events. NotificationEventThreadsafeFunction, WebviewEventThreadsafeFunction, and WebviewScriptThreadsafeFunction are exported callback aliases for consumers working directly with generated bindings.

interface ApplicationEvent {
  event: string;
  customMenuEvent?: CustomMenuEvent;
}
interface CustomMenuEvent {
  id: string;
  windowId: number;
}
interface TrayRect {
  x: number;
  y: number;
  width: number;
  height: number;
}
interface TrayEventPayload {
  event: string;
  id: string;
  x: number;
  y: number;
  rect: TrayRect;
  button?: string;
  buttonState?: string;
}
interface AndroidContentRect {
  left: number;
  top: number;
  right: number;
  bottom: number;
}

NotificationDirection, NotificationEventName, and NotificationPermission are the exported notification option/event types; see the Notification reference. PublicNewWindowEvent is a lower-level new-window payload type with an optional target; normal webview.on('new-window') listeners use WebviewNewWindowEvent.

EventListener is the listener function type used by typed emitters. TypedEventEmitter<EventMap> is a Node.js EventEmitter parameterized with an event map. BrowserWindowCloseEvent, WindowBaseEvent, WindowFileEvent, WindowImeEvent, WindowKeyEvent, WindowMouseEvent, WindowMoveEvent, WindowResizeEvent, WindowScaleEvent, WindowScrollEvent, WindowThemeEvent, WindowTouchEvent, WebviewPageLoadEvent, WebviewTitleChangedEvent, WebviewDownloadEvent, WebviewDownloadStartedEvent, WebviewNavigationEvent, and WebviewNewWindowEvent are the more specific exported event payload types.

EnumsCopy Anchor Link

Import enum members instead of hard-coding their numeric runtime values.

WebviewApplicationEvent contains WindowCloseRequested, ApplicationCloseRequested, CustomMenuClick, and Ready identifiers. WebviewEventType contains PageLoadStarted, PageLoadFinished, TitleChanged, DownloadStarted, DownloadCompleted, NavigationStarted, NewWindowRequested, DragEnter, DragOver, DragDrop, and DragLeave. WebviewEventPayload adds optional paths and position fields for native file drag events. WindowEventType contains Moved, Resized, CloseRequested, Focused, Blurred, MouseEnter, MouseLeave, MouseMove, MouseDown, MouseUp, Scroll, KeyDown, KeyUp, FileDrop, FileHover, FileHoverCancelled, ScaleFactorChanged, ThemeChanged, Ime, and Touch. These are native enum identifiers; JavaScript event listeners use the string event names in the class references and should not switch on enum ordinals. WindowCommand contains native Close, Show, and Hide identifiers and is not needed by normal applications.

ControlFlow is a backward-compatibility enum. The current application uses a non-blocking event pump; ApplicationOptions.controlFlow does not change it.

Low-level compatibility exportsCopy Anchor Link

The normal protocol API automatically handles platform URL normalization. The following exported URI workaround helpers exist for native/custom-protocol compatibility code; application code usually does not need them:

applyUriWorkAround(uri: string, httpOrHttps: string, protocol: string): string
isWorkAroundUri(uri: string, httpOrHttps: string, protocol: string): boolean
originalUriPrefix(protocol: string): string
revertUriWorkAround(uri: string, httpOrHttps: string, protocol: string): string
workAroundUriPrefix(httpOrHttps: string, protocol: string): string

getWebviewVersion(): string returns the native webview engine version where the platform backend provides one. VERSION is the installed @webviewjs/webview package version.

JsWebview, JsWebContext, JsTrayIcon, and JsNotification are generated binding aliases. NativeNotification is the native notification wrapper used by the public Notification class. Prefer Webview, WebContext, TrayIcon, and Notification in application code.

JsonValue, ExposedTarget, and SerializationError describe the webview.expose() bridge. Values must follow the JSON serialization rules documented there.