WebView2 class

A WebView2 is a twinBASIC control that hosts the Microsoft Edge WebView2 runtime — drop one onto a Form and the running Edge engine renders web content inside its rectangle. Application code can navigate to URLs, run JavaScript, intercept HTTP requests, share BASIC objects with the page, post messages back and forth, and print the document to PDF.

The control wraps the underlying ICoreWebView2* COM interfaces and exposes them as ordinary BASIC properties, methods, and events. Most of the work happens asynchronously inside the browser process — the control raises Ready once the WebView2 environment and controller have been created, and most members raise “WebView2 control is not ready” (run-time error 5) if called before then.

Private Sub Form_Load()
    WebView21.Navigate "https://www.twinbasic.com"
End Sub

Private Sub WebView21_Ready()
    Debug.Print "WebView2 ready: browser process " & WebView21.BrowserProcessId
End Sub

Private Sub WebView21_NavigationComplete( _
        ByVal IsSuccess As Boolean, ByVal WebErrorStatus As Long)
    If Not IsSuccess Then
        Debug.Print "Navigation failed: " & WebErrorStatus
    End If
End Sub

Lifecycle
Deferred events
JavaScript interop
Intercepting requests
Properties
Methods
Events
See Also

Lifecycle

A WebView2 control passes through three distinct phases between construction and use, each triggered by an asynchronous step in the Edge runtime:

Event	When
Create	After the container window exists, before the WebView2 environment is built. Last chance to set EnvironmentOptions.
Error	The environment or controller could not be created — typically because the WebView2 runtime is missing.
Ready	The environment, controller, and core view are all live. The control is now fully functional.

Calling navigation, scripting, or setting accessors before Ready raises run-time error 5 with the message “WebView2 control is not ready”. Where a setting depends on a newer runtime interface, the same error appears with “The executing version of WebView2 does not support the requested feature” instead — query the matching Supports…Features property first.

If the DocumentURL field has a non-empty value when Ready fires (the design-time default is https://www.twinbasic.com), the control auto-navigates to it.

Deferred events

Several runtime callbacks — PermissionRequested, NavigationStarting, WebResourceRequested, ScriptDialogOpening, DownloadStarting, and NewWindowRequested — are reentrant from the Edge side, meaning they fire on the WebView2 thread while it expects the host to either return synchronously or hold a deferral until the decision is made. Calling back into the control from inside a synchronous handler can deadlock the browser process.

When UseDeferredEvents is True (the default), the control takes the runtime’s deferral on the host’s behalf, posts the event onto the BASIC message-loop, and completes the deferral after the handler returns. Application code is therefore safe to call any other WebView2 method from inside these events. Set UseDeferredEvents to False only when synchronous semantics are required and the host has arranged its own re-entrancy guard.

AcceleratorKeyPressed is always synchronous — its runtime arguments do not expose a deferral.

JavaScript interop

The control offers three families of BASIC ↔ JavaScript bridges:

Host-object sharing — AddObject publishes a COM object to JavaScript under chrome.webview.hostObjects.<Name>. The page can call methods and read / write properties on the BASIC object directly. Requires AreHostObjectsAllowed (default True). Pass UseDeferredInvoke:=True when the page may call back during a BASIC operation; with deferred invocation the host cannot return values to the page.
Posting messages — PostWebMessage sends a value to the page, where it shows up via window.chrome.webview.addEventListener('message', …). The page replies with window.chrome.webview.postMessage(…), which fires the JsMessage event. Requires IsWebMessageEnabled (default True).
Executing script — JsRun calls a named JavaScript function and waits for the result, JsRunAsync calls one and fires JsAsyncResult when the result arrives, JsProp evaluates an expression like document.title, and ExecuteScript fires-and-forgets.

Intercepting requests

To rewrite, mock, or simply observe HTTP traffic from the page, register a URL filter with AddWebResourceRequestedFilter and handle WebResourceRequested. The event arguments expose a WebView2Request (read-only metadata, mutable body) and a WebView2Response — assign StatusCode, ReasonPhrase, Headers, and content to the response object to short-circuit the network fetch; leave it untouched to let the runtime proceed normally.

Properties

The control inherits the standard size, layout, and focus members from BaseControlFocusableNoFont. The bulk of the WebView2-specific members are split between settings that map to the Edge runtime, capability-flags that probe the loaded runtime version, and runtime-only state.

AdditionalAllowedFrameAncestors

Additional Content-Security-Policy: frame-ancestors directives allowed when this control hosts the page. String. Default: empty. Applies on the next navigation; effective only on runtimes that implement ICoreWebView2NavigationStartingEventArgs2.

Anchors

The container-edge anchors that control automatic resizing when the parent Form is resized. Inherited from BaseControlRectDockable.

AreBrowserAcceleratorKeysEnabled

Whether Edge’s built-in accelerator keys are active — F5 to reload, Ctrl+P to print, Ctrl+F to find in page, and so on. Boolean, default True. Requires SupportsAcceleratorKeysFeatures.

AreDefaultContextMenusEnabled

Whether Edge’s right-click context menu is shown. Boolean, default True. Set to False and handle UserContextMenu to draw a custom menu.

AreDefaultScriptDialogsEnabled

Whether Edge shows its own dialogs for alert(), confirm(), prompt(), and the beforeunload confirmation. Boolean, default True. Set to False and handle ScriptDialogOpening to provide custom dialogs.

AreDevToolsEnabled

Whether the user can open the DevTools window from the context menu or by keyboard shortcut. Boolean, default True. Independent of OpenDevToolsWindow, which always works.

AreHostObjectsAllowed

Whether host BASIC objects can be exposed to the page through AddObject. Boolean, default True.

BackColor

The colour painted behind the WebView2 surface while it is still loading and in design mode. OLE_COLOR, default &HA0BD95 (a pale green). Once the page is rendered, Edge owns the visible pixels.

BrowserProcessId

The Win32 process ID of the external msedgewebview2.exe host process. Long. Read-only. Available after Ready.

CanGoBack

Whether the browsing history has an entry behind the current document. Boolean. Read-only. Available after Ready.

CanGoForward

Whether the browsing history has an entry ahead of the current document. Boolean. Read-only. Available after Ready.

CausesValidation

Whether moving focus into the control fires the Validate event on the previously focused control. Boolean, default True. Inherited.

Container

The parent Form / Frame / PictureBox / UserControl that hosts this control. Inherited.

ControlType

Always vbWebView2 (ControlTypeConstants). Read-only. Inherited.

DocumentTitle

The current document’s <title> text. String. Read-only. Updated each time the page changes its title — the DocumentTitleChanged event fires on every update.

DocumentURL

The current document’s URL. String. Reading returns the live URL after every navigation; assigning is equivalent to calling Navigate. The design-time default is https://www.twinbasic.com, used as the auto-navigation target when Ready fires.

DragIcon

A StdPicture used as the mouse cursor during a manual drag from this control. Inherited.

DragMode

How drag-and-drop is initiated. A member of DragModeConstants: vbManual (0, default — call Drag from code) or vbAutomatic (1). Inherited.

Enabled

Whether the control accepts user input. Boolean, default True. Inherited.

EnvironmentOptions

The WebView2EnvironmentOptions object that configures the WebView2 environment — user-data folder, executable folder, locale, tracking-prevention, single-sign-on, and additional command-line arguments. The control auto-creates one on initialization; assign to its fields before or during the Create event for them to take effect.

Height

The control’s height. Single. Inherited.

hWnd

The Win32 window handle of the container window that hosts the WebView2 surface — not the HWND of the Edge browser tab itself, which lives in a separate process. LongPtr. Read-only. Overrides the inherited definition.

Index

The control-array index when the control is part of an array. Long. Read-only. Inherited.

IsBuiltInErrorPageEnabled

Whether Edge’s default error pages (e.g. Hmm, can’t reach this page) are shown. Boolean, default True.

IsDefaultDownloadDialogOpen

Whether the built-in Edge download manager dialog is currently visible. Boolean. Read-only. Requires SupportsDownloadDialogFeatures.

IsDocumentPlayingAudio

Whether the current document is producing audio. Boolean. Read-only. Requires SupportsAudioFeatures.

IsGeneralAutoFillEnabled

Whether Edge offers to save and autofill non-password form values (addresses, phone numbers, …). Boolean, default True. Requires SupportsAutoFillFeatures.

IsMuted

Whether the document’s audio is muted. Boolean, default False. Requires SupportsAudioFeatures.

IsPasswordAutoSaveEnabled

Whether Edge offers to save passwords typed into the page. Boolean, default True. Requires SupportsAutoFillFeatures.

IsPinchZoomEnabled

Whether pinch gestures on touch hardware change the zoom factor. Boolean, default True. Requires SupportsPinchZoomFeatures.

IsScriptEnabled

Whether JavaScript runs in the page. Boolean, default True. Disabling also disables every JavaScript-interop feature on the control.

IsStatusBarEnabled

Whether Edge shows its built-in status bar for hovered links. Boolean, default True.

IsSuspended

Whether the WebView2 processing pipeline has been paused by a Suspend call. Boolean. Read-only. Requires SupportsSuspendResumeFeatures.

IsSwipeNavigationEnabled

Whether horizontal swipe gestures on touch hardware navigate back / forward in history. Boolean, default True. Requires SupportsSwipeNavigationFeatures.

IsWebMessageEnabled

Whether the PostWebMessage bridge and the JsMessage event are active. Boolean, default True.

IsZoomControlEnabled

Whether the user can change the zoom factor with Ctrl+ mousewheel or Ctrl+ plus / minus. Boolean, default True.

JsCallTimeOutSeconds

How long JsRun and JsProp wait for a synchronous JavaScript result before raising RPC_E_TIMEOUT. Double seconds; 0 (default) waits indefinitely.

Left

The control’s horizontal position within its container. Double. Inherited.

MouseIcon

A StdPicture used as the mouse cursor when MousePointer is vbCustom. Inherited.

MousePointer

The mouse cursor over the control. A member of MousePointerConstants. Inherited.

Name

The design-time name. String. Read-only at runtime. Inherited.

SupportsAcceleratorKeysFeatures

Whether the loaded WebView2 runtime supports the accelerator-key settings — i.e. exposes ICoreWebView2Settings3. Boolean. Read-only.

SupportsAudioFeatures

Whether the loaded runtime supports the audio settings — i.e. exposes ICoreWebView2_8. Boolean. Read-only.

SupportsAutoFillFeatures

Whether the loaded runtime supports the autofill settings — i.e. exposes ICoreWebView2Settings4. Boolean. Read-only.

SupportsDownloadDialogFeatures

Whether the loaded runtime supports controlling the download dialog — i.e. exposes ICoreWebView2_9. Boolean. Read-only.

SupportsFolderMappingFeatures

Whether the loaded runtime supports virtual-host-to-folder mapping — i.e. exposes ICoreWebView2_5. Boolean. Read-only.

SupportsNavigateCustomFeatures

Whether the loaded runtime supports the custom-request navigation feature used by NavigateCustom — i.e. exposes ICoreWebView2_2. Boolean. Read-only.

SupportsPdfFeatures

Whether the loaded runtime supports PrintToPdf — i.e. exposes ICoreWebView2_7. Boolean. Read-only.

SupportsPinchZoomFeatures

Whether the loaded runtime supports the pinch-zoom setting — i.e. exposes ICoreWebView2Settings5. Boolean. Read-only.

SupportsSuspendResumeFeatures

Whether the loaded runtime supports Suspend / Resume — i.e. exposes ICoreWebView2_3. Boolean. Read-only.

SupportsSwipeNavigationFeatures

Whether the loaded runtime supports the swipe-navigation setting — i.e. exposes ICoreWebView2Settings6. Boolean. Read-only.

SupportsTaskManagerFeatures

Whether the loaded runtime supports OpenTaskManagerWindow — i.e. exposes ICoreWebView2_6. Boolean. Read-only.

SupportsUserAgentFeatures

Whether the loaded runtime supports the UserAgent setting — i.e. exposes ICoreWebView2Settings2. Boolean. Read-only.

TabIndex

The control’s position in the form’s TAB-key navigation order. Long. Inherited.

TabStop

Whether the user can reach the control with the TAB key. Boolean, default True. Inherited.

Tag

A free-form String the application can use to associate custom data with the control. Inherited.

Top

The control’s vertical position within its container. Double. Inherited.

UseDeferredEvents

Whether the re-entrant runtime events (PermissionRequested, NavigationStarting, WebResourceRequested, ScriptDialogOpening, DownloadStarting, NewWindowRequested) are deferred onto the BASIC message-loop before they fire. Boolean, default True. See Deferred events.

UserAgent

The User-Agent string Edge sends with each HTTP request. String. Setting it persists for the lifetime of the environment. Requires SupportsUserAgentFeatures.

Visible

Whether the control is shown. Boolean, default True. Inherited.

Width

The control’s width. Single. Inherited.

ZoomFactor

The current zoom factor — 1.0 is 100%, 1.5 is 150%, and so on. Double. The design-time default is 0, which means “do not override Edge’s default of 1.0”.

Note

Because the design-time default is 0, not 1.0, arithmetic that multiplies the current value silently starts from zero unless the host clamps it to 1 first:

If WebView21.ZoomFactor = 0 Then WebView21.ZoomFactor = 1
WebView21.ZoomFactor *= 1.1   ' 110% on first click, 121% on second, …

Methods

AddObject

Exposes a BASIC COM object to the page under chrome.webview.hostObjects.<ObjName>. The page can read and write its properties and call its methods as ordinary JavaScript objects.

Syntax: object.AddObject ObjName, Object [, UseDeferredInvoke ]

ObjName: required A String name for the page to reference the object under.
Object: required An Object to publish.
UseDeferredInvoke: optional A Boolean, default False. When True, calls from the page are deferred onto the BASIC message-loop — safe to re-enter the WebView2 control from within them, but the page cannot read a return value back. Use False when the page needs to read return values.

Private Sub WebView21_Ready()
    WebView21.AddObject "myCalculator", New MyCalculator
End Sub

Class MyCalculator
    Public Function MultiplyByTen(ByVal Value As Long) As Long
        Return Value * 10
    End Function
End Class

async function callHostCalculator() {
    let result = await chrome.webview.hostObjects.myCalculator.MultiplyByTen(7);
    alert("BASIC returned: " + result);   //  -> 70
}

Calls into the host object are asynchronous on the JavaScript side and must be await-ed inside an async function — even when UseDeferredInvoke is False. See the Re-entrancy tutorial for when to pass True.

AddScriptToExecuteOnDocumentCreated

Registers a JavaScript snippet to be run automatically at the top of every new document the WebView2 navigates to. Takes effect on the next navigation — does not affect the page currently loaded.

Syntax: object.AddScriptToExecuteOnDocumentCreated jsCode

jsCode: required A String containing the JavaScript code to inject.

AddWebResourceRequestedFilter

Registers a URL pattern. Requests whose URI matches the pattern fire the WebResourceRequested event so the host can observe or override them.

Syntax: object.AddWebResourceRequestedFilter sFilter, FilterContext

sFilter: required A String URL pattern. * and ? are wildcards.
FilterContext: required A member of wv2WebResourceContext restricting matches to a particular resource kind.

CallDevToolsProtocolMethod

Sends a Chrome DevTools Protocol message to the running Edge instance. When CustomEventId is provided, the runtime’s reply fires the DevToolsProtocolResponse event with the same CustomEventId and the JSON response.

Syntax: object.CallDevToolsProtocolMethod MethodName, ParamsAsJson [, CustomEventId ]

MethodName: required A String like "Emulation.setScriptExecutionDisabled".
ParamsAsJson: required A String with the JSON-encoded parameter object.
CustomEventId: optional A Variant echoed back on DevToolsProtocolResponse. When omitted, the reply is discarded.

ClearVirtualHostNameToFolderMapping

Removes a virtual hostname → local-folder mapping previously installed by SetVirtualHostNameToFolderMapping.

Syntax: object.ClearVirtualHostNameToFolderMapping hostName

hostName: required A String matching the hostname passed to SetVirtualHostNameToFolderMapping.

Requires SupportsFolderMappingFeatures.

CloseDefaultDownloadDialog

Hides the built-in Edge download manager dialog.

Syntax: object.CloseDefaultDownloadDialog

Requires SupportsDownloadDialogFeatures.

Drag

Begins, completes, or cancels a manual drag-and-drop operation. Inherited.

Syntax: object.Drag [ Action ]

ExecuteScript

Evaluates JavaScript in the page without waiting for it to finish and without returning its result. Use JsRun or JsRunAsync when the value is needed.

Syntax: object.ExecuteScript jsCode

jsCode: required A String of JavaScript to evaluate in the page’s global scope.

GoBack

Navigates one entry back in the browsing history. Silently does nothing when CanGoBack is False.

Syntax: object.GoBack

GoForward

Navigates one entry forward in the browsing history. Silently does nothing when CanGoForward is False.

Syntax: object.GoForward

JsProp

Evaluates a JavaScript expression and returns the result synchronously — convenient for property reads like document.title. Waits up to JsCallTimeOutSeconds for the result.

Syntax: object.JsProp ( PropName ) As Variant

PropName: required A String containing the expression to evaluate.

Returns the result decoded from the JSON the runtime returns — Boolean, Double, String, Null, or Empty (for undefined). Object and array results are not yet supported — accessing them raises run-time error 5.

JsRun

Calls a named JavaScript function with the given arguments and returns the result synchronously. Waits up to JsCallTimeOutSeconds for the result.

Syntax: object.JsRun ( FuncName, [ args ] ) As Variant

FuncName: required A String naming the JavaScript function — e.g. "document.querySelector".
args: optional Any number of Variant arguments. Each is JSON-encoded before being passed to the function. Strings, numerics, Boolean, Null, and Empty are supported.

' Calls the page-side function `multiplyTheseNumbers(a, b)` and waits for the result.
Dim product As Long = WebView21.JsRun("multiplyTheseNumbers", 5, 6)
Debug.Print product   ' 30

JsRunAsync

Calls a named JavaScript function asynchronously and returns immediately with a token. When the result arrives, JsAsyncResult fires with the same token.

Syntax: object.JsRunAsync ( FuncName, [ args ] ) As LongLong

FuncName: required A String naming the JavaScript function.
args: optional Any number of Variant arguments, JSON-encoded as in JsRun.

Private Sub btnRun_Click()
    WebView21.JsRunAsync "multiplyTheseNumbers", 5, 6
End Sub

Private Sub WebView21_JsAsyncResult( _
        ByVal Result As Variant, Token As LongLong, ErrString As String)
    If LenB(ErrString) = 0 Then
        Debug.Print "Async result: "; Result
    Else
        Debug.Print "Async error: "; ErrString
    End If
End Sub

Move

Repositions and resizes the control in a single call. Inherited.

Syntax: object.Move Left [, Top [, Width [, Height ] ] ]

MoveFocus

Transfers keyboard focus to the underlying WebView2 surface so that subsequent keystrokes are dispatched into the page. Distinct from the inherited SetFocus, which focuses the host control window.

Syntax: object.MoveFocus

Navigate

Loads a URL into the WebView2. Fires NavigationStarting and then NavigationComplete. If the URI has no protocol prefix, https:// is added automatically.

Syntax: object.Navigate uri

uri: required A String URI such as "https://www.twinbasic.com" or "file:///C:/page.html".

Private Sub AddressBar_KeyDown(KeyCode As Integer, Shift As Integer)
    If KeyCode = vbKeyReturn Then WebView21.Navigate AddressBar.Text
End Sub

Private Sub WebView21_NavigationComplete( _
        ByVal IsSuccess As Boolean, ByVal WebErrorStatus As Long)
    btnBack.Enabled = WebView21.CanGoBack
    btnForward.Enabled = WebView21.CanGoForward
End Sub

NavigateCustom

Navigates with an arbitrary HTTP method, optional headers, and an optional request body — useful for POST navigation or attaching authorization headers up front. Fires NavigationStarting and NavigationComplete.

Syntax: object.NavigateCustom uri, method [, headers [, postData [, postDataAsUTF8 ] ] ]

uri: required A String URI. As with Navigate, a missing protocol prefix is patched to https://.
method: required A String HTTP method — "GET", "POST", …
headers: optional A String of vbCrLf-delimited Header: value lines.
postData: optional A Variant containing the body — a String (encoded according to postDataAsUTF8) or a Byte() array (used verbatim).
postDataAsUTF8: optional A Boolean, default True. When True and postData is a String, the string is UTF-8-encoded before being sent.

Requires SupportsNavigateCustomFeatures.

NavigateToString

Loads an HTML string directly into the WebView2 as if it were the body of an HTTP response — useful for splash screens, generated reports, or about pages. Fires NavigationStarting and NavigationComplete.

Syntax: object.NavigateToString htmlContent

htmlContent: required A String of HTML source.

WebView21.NavigateToString "<h1>Hello, world!</h1>"

OpenDefaultDownloadDialog

Shows the built-in Edge download manager dialog.

Syntax: object.OpenDefaultDownloadDialog

Requires SupportsDownloadDialogFeatures.

OpenDevToolsWindow

Opens the DevTools window for the page in a separate Edge window. Works independently of AreDevToolsEnabled, which only governs the user-initiated path.

Syntax: object.OpenDevToolsWindow

OpenTaskManagerWindow

Opens Edge’s browser-task manager window listing the renderer processes used by the control.

Syntax: object.OpenTaskManagerWindow

Requires SupportsTaskManagerFeatures.

PostWebMessage

Posts a value to the page. The page receives it via a message event on window.chrome.webview. Strings are delivered as JavaScript strings; every other type is JSON-encoded before being sent.

Syntax: object.PostWebMessage Message

Message: required A Variant value to send.

Requires IsWebMessageEnabled.

WebView21.PostWebMessage "Hello from twinBASIC!"

Private Sub WebView21_JsMessage(ByVal Message As Variant)
    Debug.Print "Reply from page: "; Message
End Sub

window.chrome.webview.addEventListener('message', (e) => {
    alert("Host sent: " + e.data);
    window.chrome.webview.postMessage("Thanks, twinBASIC!");
});

PostWebMessageJSON

Posts a literal JSON string to the page without re-encoding it — useful when the caller already has serialised JSON.

Syntax: object.PostWebMessageJSON jsonString

jsonString: required A String of valid JSON.

Requires IsWebMessageEnabled.

PrintToPdf

Saves the current document to a PDF file. The work happens asynchronously — the result arrives through PrintToPdfCompleted or PrintToPdfFailed. Requires SupportsPdfFeatures.

Syntax: object.PrintToPdf outputPath [, Orientation [, ScaleFactor [, PageWidth [, PageHeight [, MarginTop [, MarginBottom [, MarginLeft [, MarginRight [, ShouldPrintBackgrounds [, ShouldPrintSelectionOnly [, ShouldPrintHeaderAndFooter [, HeaderTitle [, FooterUri ] ] ] ] ] ] ] ] ] ] ] ] ]

outputPath: required A String absolute path to the PDF file to write.
Orientation: optional A member of wv2PrintOrientation. Default wv2PrintPortrait.
ScaleFactor, PageWidth, PageHeight, MarginTop, MarginBottom, MarginLeft, MarginRight: optional Doubles describing the page layout. Omit any of them to use the runtime defaults.
ShouldPrintBackgrounds: optional A Boolean, default False.
ShouldPrintSelectionOnly: optional A Boolean, default False.
ShouldPrintHeaderAndFooter: optional A Boolean, default True.
HeaderTitle, FooterUri: optional Strings overriding the default header title and footer URI.

Private Sub btnSave_Click()
    WebView21.PrintToPdf Environ$("USERPROFILE") & "\Documents\page.pdf"
End Sub

Private Sub WebView21_PrintToPdfCompleted()
    MsgBox "PDF saved.", vbInformation
End Sub

Reload

Reloads the current document — equivalent to pressing F5.

Syntax: object.Reload

RemoveObject

Removes a host object previously published with AddObject.

Syntax: object.RemoveObject ObjName

ObjName: required A String matching the name passed to AddObject.

RemoveWebResourceRequestedFilter

Removes a URL filter previously registered with AddWebResourceRequestedFilter. Pass the same sFilter and FilterContext values used to register it.

Syntax: object.RemoveWebResourceRequestedFilter sFilter, FilterContext

sFilter: required A String URL pattern.
FilterContext: required A member of wv2WebResourceContext.

Resume

Resumes a previously suspended WebView2 pipeline. Fires no event — read IsSuspended afterwards to confirm.

Syntax: object.Resume

Requires SupportsSuspendResumeFeatures.

SetFocus

Moves the input focus to the host control. Inherited. To focus the page surface so keystrokes reach JavaScript, use MoveFocus instead.

Syntax: object.SetFocus

SetVirtualHostNameToFolderMapping

Maps a virtual hostname to a local folder so that a page can reference local files through HTTPS URLs — e.g. https://app.local/index.html resolves to C:\MyApp\html\index.html. Useful for hosting local assets without setting up an HTTP server.

Syntax: object.SetVirtualHostNameToFolderMapping hostName, folderPath [, accessKind ]

hostName: required A String virtual hostname.
folderPath: required A String local folder path.
accessKind: optional A member of wv2HostResourceAccessKind. Default wv2ResourceAllow.

Note

Pick the hostName carefully — certain DNS-resolvable hostnames cause a 2-second resolution stall before the local override kicks in. See WebView2Feedback#2381.

Requires SupportsFolderMappingFeatures.

Private Sub WebView21_Ready()
    Dim folderPath As String = Environ$("USERPROFILE") & "\Documents\MyApp"
    WebView21.SetVirtualHostNameToFolderMapping _
        "myapp.example", folderPath & "\", wv2ResourceAllow
    WebView21.Navigate "https://myapp.example/index.html"
End Sub

See the Hosting local web assets tutorial for the matching pattern of bundling the assets through the project’s Resources folder.

Suspend

Pauses the WebView2 pipeline so the browser process can free memory — useful for application-style tab management. Read IsSuspended afterwards to confirm; the runtime hides the control while suspended.

Syntax: object.Suspend

Requires SupportsSuspendResumeFeatures.

ZOrder

Brings the control to the front or back of its sibling stack. Inherited.

Syntax: object.ZOrder [ Position ]

Events

AcceleratorKeyPressed

Raised when Edge detects an accelerator-style keystroke — e.g. F1, Alt+, Ctrl+. Set IsHandled to True to consume the keystroke so Edge doesn’t act on it. Always synchronous: cannot be deferred.

Syntax: object_AcceleratorKeyPressed( KeyState As wv2KeyEventKind, IsExtendedKey As Boolean, WasKeyDown As Boolean, IsKeyReleased As Boolean, IsMenuKeyDown As Boolean, RepeatCount As Long, ScanCode As Long, IsHandled As Boolean )

The flags are the contents of the Win32 WM_KEYDOWN / WM_KEYUP lParam — see COREWEBVIEW2_PHYSICAL_KEY_STATUS for the full breakdown.

Create

Raised after the container window exists but before the WebView2 environment is built. The host’s last chance to populate EnvironmentOptions.

Syntax: object_Create( )

DevToolsProtocolResponse

Raised when a previously sent CallDevToolsProtocolMethod call returns. Includes the CustomEventId supplied at the call site and the JSON-encoded response.

Syntax: object_DevToolsProtocolResponse( CustomEventId As Variant, JsonResponse As String )

DocumentTitleChanged

Raised when the document changes its title — typically right after a navigation, but also when client-side JavaScript writes to document.title. Read DocumentTitle for the new value.

Syntax: object_DocumentTitleChanged( )

DOMContentLoaded

Raised when the page reaches the DOMContentLoaded lifecycle event — the DOM tree is built and JavaScript can safely walk it, but external resources may still be loading.

Syntax: object_DOMContentLoaded( )

DownloadStarting

Raised when the user (or the page) starts a file download. Set Cancel to True to suppress the download; set Handled to True to suppress the runtime’s default download UI when the application intends to manage progress itself. Modify ResultFilePath to redirect the download to a different path. Can be deferred — see Deferred events.

Syntax: object_DownloadStarting( ResultFilePath As String, Cancel As Boolean, Handled As Boolean )

Error

Raised when the WebView2 environment or controller fails to initialise — most commonly because the Edge WebView2 runtime isn’t installed, the user-data folder isn’t writable, or the fixed-version folder is incorrect.

Syntax: object_Error( code As Long, msg As String )

Note

Code &H80070002 (ERROR_FILE_NOT_FOUND) is the canonical signal that the WebView2 Evergreen runtime is missing from the machine — the right cue to prompt the user to install it.

Private Sub WebView21_Error(ByVal code As Long, ByVal msg As String)
    Const ERROR_FILE_NOT_FOUND As Long = &H80070002
    If code = ERROR_FILE_NOT_FOUND Then
        MsgBox "The WebView2 (Evergreen) runtime is not installed on this machine.", _
               vbExclamation, "WebView2"
    Else
        MsgBox "WebView2 error " & Hex$(code) & ": " & msg, _
               vbExclamation, "WebView2"
    End If
End Sub

JsAsyncResult

Raised when an earlier JsRunAsync call returns. Token is the value returned by JsRunAsync so the handler can pair replies with calls; ErrString is a description of any runtime error, or an empty string on success.

Syntax: object_JsAsyncResult( Result As Variant, Token As LongLong, ErrString As String )

JsMessage

Raised when JavaScript on the page calls window.chrome.webview.postMessage(value). Requires IsWebMessageEnabled.

Syntax: object_JsMessage( Message As Variant )

NavigationComplete

Raised after a navigation finishes — successfully or otherwise. Inspect IsSuccess first; if False, WebErrorStatus is a member of wv2ErrorStatus.

Syntax: object_NavigationComplete( IsSuccess As Boolean, WebErrorStatus As Long )

NavigationStarting

Raised before each navigation begins. Set Cancel to True to block the navigation; modify RequestHeaders to alter the HTTP request the runtime is about to send. Can be deferred — see Deferred events.

Syntax: object_NavigationStarting( Uri As String, IsUserInitiated As Boolean, IsRedirected As Boolean, RequestHeaders As WebView2RequestHeaders, Cancel As Boolean )

' Block any navigation to a URL outside our own virtual host.
Private Sub WebView21_NavigationStarting( _
        ByVal Uri As String, ByVal IsUserInitiated As Boolean, _
        ByVal IsRedirected As Boolean, _
        ByVal RequestHeaders As WebView2RequestHeaders, _
        Cancel As Boolean)
    If Not (Uri Like "https://myapp.example/*" Or Uri = "about:blank") Then
        MsgBox "External link blocked: " & Uri
        Cancel = True
    End If
End Sub

NewWindowRequested

Raised when the page tries to open a new window — via window.open(…), target="_blank", Ctrl+ click, and so on. Set IsHandled to True to suppress the default behaviour (which opens a fresh Edge window) so the application can host the new content itself. The window-features arguments describe what the page asked for. Can be deferred — see Deferred events.

Syntax: object_NewWindowRequested( IsUserInitiated As Boolean, IsHandled As Boolean, Uri As String, HasPosition As Long, HasSize As Long, Left As Long, Top As Long, Width As Long, Height As Long, ShouldDisplayMenuBar As Long, ShouldDisplayStatus As Long, ShouldDisplayToolbar As Long, ShouldDisplayScrollBars As Long )

PermissionRequested

Raised when the page asks for permission to use a device or browser capability — camera, microphone, geolocation, notifications, clipboard. Assign State to grant (wv2StateAllow) or deny (wv2StateDeny); leave it at wv2StateDefault to let Edge prompt the user. Can be deferred — see Deferred events.

Syntax: object_PermissionRequested( IsUserInitiated As Boolean, State As wv2PermissionState, Uri As String, PermissionKind As wv2PermissionKind )

PrintToPdfCompleted

Raised when PrintToPdf finishes successfully.

Syntax: object_PrintToPdfCompleted( )

PrintToPdfFailed

Raised when PrintToPdf fails — e.g. the output path was not writable.

Syntax: object_PrintToPdfFailed( )

ProcessFailed

Raised when one of WebView2’s external processes (the browser, renderer, GPU, …) exits unexpectedly. Inspect Kind — a wv2ProcessFailedKind — to find out which.

Syntax: object_ProcessFailed( Kind As wv2ProcessFailedKind )

Ready

Raised once the WebView2 environment, controller, and core view are all live. Until this point most properties and methods raise “WebView2 control is not ready”.

Syntax: object_Ready( )

ScriptDialogOpening

Raised when the page tries to open a script dialog — alert(), confirm(), prompt(), or beforeunload. Only fires when AreDefaultScriptDialogsEnabled is False. Set Accept to True to accept the dialog (the JavaScript-side equivalent of clicking OK); for prompts, update ResultText with the text to return. Can be deferred — see Deferred events.

Syntax: object_ScriptDialogOpening( ScriptDialogKind As wv2ScriptDialogKind, Accept As Boolean, ResultText As String, URI As String, Message As String, DefaultText As String )

SourceChanged

Raised when DocumentURL changes — typically right after a navigation, but also when client-side script calls history.pushState(…). IsNewDocument distinguishes a real navigation (True) from a same-document URL change (False).

Syntax: object_SourceChanged( IsNewDocument As Boolean )

SuspendCompleted

Raised when a Suspend request finishes successfully.

Syntax: object_SuspendCompleted( )

SuspendFailed

Raised when a Suspend request fails — typically because the page is still doing something the runtime cannot suspend.

Syntax: object_SuspendFailed( )

UserContextMenu

Raised when the user right-clicks inside the control and AreDefaultContextMenusEnabled is False, so the application can show its own context menu.

Syntax: object_UserContextMenu( X As Single, Y As Single )

WebResourceRequested

Raised when a pending HTTP request matches a filter previously registered with AddWebResourceRequestedFilter. Modify Response to mock or override the reply; leave it untouched to let the runtime fetch normally. Can be deferred — see Deferred events.

Syntax: object_WebResourceRequested( Request As WebView2Request, Response As WebView2Response )