Overview of WebView2 features and APIs
Embedding the WebView2 control in your app gives your app access to various methods and properties that are provided through the WebView2 classes or interfaces. WebView2 has hundreds of APIs that provide a vast set of capabilities, ranging from enhancing your app's native-platform capabilities, to enabling your app to modify browser experiences. This article provides a high-level grouping of the WebView2 APIs to help you understand the different things you can do using WebView2.
When hosting the WebView2 control, your app has access to the following features and APIs:
|Main classes: Environment, Controller, and Core||The
|Browser features||The WebView2 control gives your app access to many browser features. You can modify these browser features and turn them on or off.|
|Process management||Get information about running WebView2 processes, exiting processes, and failed processes, so your app can take action accordingly.|
|Navigate to pages and manage loaded content||Manage navigation to webpages and manage content that's loaded in the webpages.|
|iFrames||Embed other webpages into your own webpage. Detect when embedded webpages are created, detect when embedded webpages are navigating, and optionally bypass x-frame options.|
|Authentication||Your app can handle basic authentication using the WebView2 control. Basic authentication is a specific authentication approach that's part of the HTTP protocol.|
|Rendering WebView2 in non-framework apps||Use these APIs to set up the WebView2 rendering system if your host app doesn't use a UI framework. This rendering setup controls how WebView2 renders output into your host app, and how WebView2 handles input, focus, and accessibility.|
|Rendering WebView2 using Composition||For composition-based WebView2 rendering, use
|User data||Manage the user data folder (UDF), which is a folder on the user's machine. The UDF contains data related to the host app and WebView2. WebView2 apps use user data folders to store browser data, such as cookies, permissions, and cached resources.|
|Performance and debugging||Analyze and debug performance, handle performance-related events, and manage memory usage to increase the responsiveness of your app.|
|Chrome Developer Protocol (CDP)||Instrument, inspect, debug, and profile Chromium-based browsers. The Chrome DevTools Protocol is the foundation for the Microsoft Edge DevTools. Use the Chrome DevTools Protocol for features that aren't implemented in the WebView2 platform.|
Main classes: Environment, Controller, and Core
CoreWebView2 classes (or equivalent interfaces) work together so your app can host a WebView2 browser control and access its browser features. These three large classes expose a wide range of APIs that your host app can access to provide many categories of browser-related features for your users.
CoreWebView2Environmentclass represents a group of WebView2 controls that share the same WebView2 browser process, user data folder, and renderer processes. From this
CoreWebView2Environmentclass, you create pairs of
CoreWebView2Controllerclass is responsible for hosting-related functionality such as window focus, visibility, size, and input, where your app hosts the WebView2 control.
CoreWebView2class is for the web-specific parts of the WebView2 control, including networking, navigation, script, and parsing and rendering HTML.
Some common use cases include:
- Update the native host window title after navigating to a different website.
- Send a native camera object and use its methods from a web app.
For more information, see:
- Interop of native-side and web-side code
- Call web-side code from native-side code
- Call native-side code from web-side code
The following are the main APIs for communicating between web and native code.
Host/web object sharing
WebView2 enables objects that are defined in native code to be passed to your app's web-side code. Host objects are any objects that are defined in native code that you choose to pass to your app's web-side code.
Your app can send messages to the web content that's within the WebView2 control, and receive messages from that web content. Messages are sent as strings or JSON objects.
- CoreWebView2.PostWebMessageAsJson Method
- CoreWebView2.PostWebMessageAsString Method
- CoreWebView2.WebMessageReceived Event
- CoreWebView2Settings.IsWebMessageEnabled Property
- CoreWebView2Frame.PostWebMessageAsJson Method
- CoreWebView2Frame.PostWebMessageAsString Method
- CoreWebView2Frame.WebMessageReceived Event
The WebView2 control gives your app access to many browser features. You can modify these browser features and turn them on or off.
You can configure custom print settings and print to PDF.
By hosting WebView2, your app can capture screenshots and indicate which format to use to save the image.
Your app can manage the download experience in WebView2. Your app can:
- Allow or block downloads based on different metadata.
- Change the download location.
- Configure a custom download UI.
- Customize the default UI.
- CoreWebView2.IsDefaultDownloadDialogOpenChanged Event
- CoreWebView2.IsDefaultDownloadDialogOpen Property
- CoreWebView2.OpenDefaultDownloadDialog Method
- CoreWebView2.CloseDefaultDownloadDialog Method
Modify Default Experience:
- CoreWebView2.DefaultDownloadDialogCornerAlignment Property
- CoreWebView2.DefaultDownloadDialogMargin Property
- CoreWebView2Profile.DefaultDownloadFolderPath Property
Custom Download Experience:
Different webpages may ask you for permissions to access some privileged resources, such as geolocation sensor, camera, and microphone. Your host app can programmatically respond to permissions requests and can replace the default permissions UI with its own UI.
The WebView2 control provides a default context menu (right-click menu) which you can customize or disable, and you can also create your own context menu.
A status bar is located in the bottom left of the page and displays the state of the webpage being displayed. In WebView2 you can enable/disable the status bar, get the text in the status bar, and find out when the status bar text has changed.
The user agent is a string that represents the identity of the program on behalf of the user, such as the browser name. In WebView2, you can set the user agent.
Your app can independently control whether the browser's autofill functionality is enabled for general information or for passwords.
Your app can mute and unmute all audio, and find out when audio is playing.
Swipe gesture navigation
By hosting the WebView2 control, your app can enable or disable swiping gesture navigation on touch input-enabled devices. This gesture allows end users to:
- Swipe left/right (swipe horizontally) to navigate to the previous or next page in the navigation history.
- Pull to refresh (swipe vertically) the current page.
This feature is currently disabled by default in the browser. To enable this feature in WebView2, set the
AdditionalBrowserArguments property, specifying the
In WebView2, you can find out when an HTML element enters or leaves full-screen view.
In the browser PDF viewer, there's a PDF-specific toolbar along the top. In WebView2, you can hide some of the items in the PDF viewer toolbar.
In WebView2, you can customize the color theme as system, light, or dark.
You can set the default display language for WebView2 that applies to the browser UI (such as context menus and dialogs), along with setting the
accept-language HTTP header which WebView2 sends to websites.
Your app can detect when the title of the current top-level document has changed.
In WebView2 you can you can set a Favicon for a website or get notified when it changes.
Get information about running WebView2 processes, exiting processes, and failed processes, so that your app can take action accordingly.
- CoreWebView2.BrowserProcessId Property
- CoreWebView2Environment.GetProcessInfos Method
- CoreWebView2Environment.ProcessInfosChanged Event
- CoreWebView2ProcessInfo Class
Navigate to pages and manage loaded content
Through the WebView2 control, your app can manage navigation to webpages and manage content that's loaded in the webpages.
Manage content loaded into WebView2
These APIs load, stop loading, and reload content to WebView2. The content that's loaded can be:
- Content from a URL.
- A string of HTML.
- Local content via virtual host name to local folder mapping.
- Content from a constructed network request.
- CoreWebView2.Navigate Method
- CoreWebView2.NavigateToString Method
- CoreWebView2.NavigateWithWebResourceRequest Method
- CoreWebView2.Stop Method
- CoreWebView2.Reload Method
- CoreWebView2.SetVirtualHostNameToFolderMapping Method
- CoreWebView2.ClearVirtualHostNameToFolderMapping Method
- CoreWebView2Settings.IsBuiltInErrorPageEnabled Property
The history methods allow back and forward navigation in WebView2, and the history events provide information about the changes in history and in WebView2's current source.
Block unwanted navigating
NavigationStarting event allows the app to cancel navigating to specified URLs in WebView2, including for frames.
NavigationStarting and the other navigation events, the app can be informed of the state of navigation in WebView2. A navigation is the process for loading a new URL.
- CoreWebView2.ContentLoading Event
- CoreWebView2.DOMContentLoaded Event
- CoreWebView2.NavigationCompleted Event
- CoreWebView2.FrameNavigationCompleted Event
- CoreWebView2Frame.ContentLoading Event
- CoreWebView2Frame.DOMContentLoaded Event
- CoreWebView2Frame.NavigationCompleted Event
Manage network requests in WebView2
WebResourceRequested event allows the app to intercept and override all network requests in WebView2. The
WebResourceResponseReceived event allows the app to monitor the request sent to and the response received from the network.
In WebView2, you can use the Client Certificate API to select the client certificate at the application level. This API allows you to:
- Display a UI to the user, if desired.
- Replace the default client certificate dialog prompt.
- Programmatically query the certificates.
- Select a certificate from the list to respond to the server, when WebView2 is making a request to an HTTP server that needs a client certificate for HTTP authentication.
In WebView2, you can use the Server Certificate API to trust the server's TLS certificate at the application level. This way, your host app can render the page without prompting the user about the TLS error, or your host app can automatically cancel the request.
iFrames allow you to embed other webpages into your own webpage. In WebView2, you can:
- Find out when iFrames are created.
- Find out when iFrames are navigating.
- Allow bypassing x-frame options.
Your app can handle basic authentication using the WebView2 control. Basic authentication is a specific authentication approach that's part of the HTTP protocol.
Rendering WebView2 in non-framework apps
Use these APIs to set up the WebView2 rendering system if your host app doesn't use a UI framework. This rendering setup controls how WebView2 renders output into your host app, and how WebView2 handles input, focus, and accessibility.
UI framework - If you're using a UI framework for your app, you should use the WebView2 element that's provided by that UI framework, rather than using these APIs.
No UI framework, and not using Composition - If you're not using a UI framework for your app (for example, if you're using pure Win32 directly), or if your UI framework doesn't have a WebView2 element, then you need to create
CoreWebView2Controllerand render it into your app, using these APIs in this section.
No UI framework, and using Composition - If your app UI is built using DirectComposition or Windows.UI.Composition, you should use
CoreWebView2CompositionControllerrather than using these APIs; see Rendering WebView2 using Composition, below.
Sizing, positioning, and visibility
CoreWebView2Controller takes a parent
Bounds property sizes and positions the WebView2 relative to the parent
HWND. The visibility of WebView2 can be toggled using
ZoomFactor is used to scale just the web content of the window. UI scaling is also updated when the user zooms the content by pressing
Ctrl while rotating the mouse wheel.
- CoreWebView2Controller.ZoomFactor Property
- CoreWebView2Controller.ZoomFactorChanged Event
- CoreWebView2Controller.SetBoundsAndZoomFactor Method
The RasterizationScale API scales all WebView2 UI including context menus, tooltip, and popups. The app can set whether the WebView2 should detect monitor scale changes and automatically update the RasterizationScale.
BoundsMode is used to configure whether the Bounds property is interpreted as raw pixels, or DIPs (which need to be scaled by
Focus and tabbing
The WebView2 control raises events to let the app know when the control gains focus or loses focus. For tabbing (pressing the
Tab key), there's an API to move focus into WebView2 and an event for WebView2 to request the app to take focus back.
WebView2 can be reparented to a different parent window handle (
HWND). WebView2 also needs to be notified when the app's position on the screen has changed.
When WebView2 has focus, it directly receives input from the user. An app may want to intercept and handle certain accelerator key combinations, or disable the normal browser accelerator key behaviors.
Default background color
WebView2 can specify a default background color. The color can be any opaque color, or transparent. This color will be used if the HTML page doesn't set its own background color.
Rendering WebView2 using Composition
For composition-based WebView2 rendering, use
CoreWebView2Environment to create a
CoreWebView2CompositionController provides the same APIs as
CoreWebView2Controller, but also includes APIs for composition-based rendering.
Connecting to the visual tree
Spatial input (mouse, touch, pen) is received by the application and must be sent to WebView2. WebView2 notifies the app when the cursor should be updated based on the mouse position.
- CoreWebView2CompositionController.Cursor Property
- CoreWebView2CompositionController.CursorChanged Event
- CoreWebView2CompositionController.SystemCursorId Property
- CoreWebView2CompositionController.SendMouseInput Method
- CoreWebView2CompositionController.SendPointerInput Method
- CoreWebView2Environment.CreateCoreWebView2PointerInfo Method
By default, WebView2 will show up in the accessibility tree as a child of the parent HWND, for Win32/C++ apps. WebView2 provides API to better position the WebView2 content relative to other elements in the application.
Manage the user data folder (UDF), which is a folder on the user's machine. The UDF contains data related to the host app and WebView2. WebView2 apps use user data folders to store browser data, such as cookies, permissions, and cached resources.
- CoreWebView2Environment.UserDataFolder Property
- CoreWebView2EnvironmentOptions.ExclusiveUserDataFolderAccess Property
- CoreWebView2Profile.ClearBrowsingDataAsync Method
- CoreWebView2Environment.CreateCoreWebView2CompositionControllerAsync Method
- CoreWebView2Environment.CreateCoreWebView2ControllerOptions Method
- CoreWebView2Environment.CreateCoreWebView2ControllerWithOptions Method
Performance and debugging
Analyze and debug performance, handle performance-related events, and manage memory usage to increase the responsiveness of your app.
Chrome Developer Protocol (CDP)
The Chrome DevTools Protocol provides APIs to instrument, inspect, debug, and profile Chromium-based browsers. The Chrome DevTools Protocol is the foundation for the Microsoft Edge DevTools. Use the Chrome DevTools Protocol for features that aren't implemented in the WebView2 platform.
- CoreWebView2.CallDevToolsProtocolMethodAsync Method
- CoreWebView2.CallDevToolsProtocolMethodForSessionAsync Method
Submit and view feedback for