Navigation events for WebView2 apps
Supported platforms: Win32, Windows Forms, WinUi, WPF.
This article covers navigation events for WebView2 apps. Navigation events run when specific asynchronous actions occur to the content that's displayed in a WebView2 instance. For example, when a WebView2 user navigates to a new website, the native content listens for the change by listening for the
NavigationStarting event. When the navigation action completes,
For an example of navigation events, see Get started with WebView2.
The normal sequence of navigation events is:
The following events describe the state of WebView2 during each navigation action:
||WebView2 starts to navigate and the navigation results in a network request. The host may disallow the request during the event.|
||The source of WebView2 changes to a new URL. The event may result from a navigation action that doesn't cause a network request such as a fragment navigation.|
||WebView2 starts loading content for the new page.|
||The navigation causes the history of WebView2 to update.|
||WebView2 finishes parsing the DOM content but hasn't finished loading all images, script, and other content on the page.|
||WebView2 completes loading content on the new page.|
The above figure shows navigation events that have the same
NavigationId property on the respective event argument.
Track navigation events to each new document by using the navigation ID (which is provided in the
NavigationId event). The
NavigationId event of WebView2 changes every time a successful navigation to a new document completes.
Navigation events with different instances of
NavigationId event may overlap. For instance, when you start a navigation event, you must wait for the related
NavigationStarting event. If you then start another navigation, you'll see the following sequence:
NavigationStartingevent for the first navigation.
NavigationStartingevent for the second navigation.
NavigationCompletedevent for the first navigation.
- All the rest of the appropriate navigation events for the second navigation.
In error cases, there may or may not be a
ContentLoading event, depending on whether the navigation is continued to an error page.
If an HTTP redirect occurs, there are multiple
NavigationStarting events in a row, where later event arguments have the
IsRedirect property set; however, the
NavigationId event remains the same.
Same-document navigation events, such as navigating to a fragment in the same document, don't cause a
NavigationStarting event, and don't increment the
To monitor or cancel navigation events inside subframes in a WebView2 instance, use the
FrameNavigationCompleted events. Those events act like the equivalent non-frame, counterpart events.
Submit and view feedback for