Navigation events for WebView2 apps
When the user of your WebView2 app goes to a different webpage, URL, or file path, this is a navigation. Each navigation fires a sequence of navigation-related events. The native portion of your WebView2 app listens for these navigation events and handles them.
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,
Supported platforms: Win32, Windows Forms, WinUI, WPF.
Standard sequence of events
The following is the normal sequence of events that are fired during each step of a navigation:
|Sequence||Event||Description||API Reference overview|
||WebView2 starts to navigate and the navigation results in a network request. The host may disallow the request during the event.||Block unwanted navigating|
||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.||Navigation history|
||WebView2 starts loading content for the new page.||Navigation events|
||The navigation causes the history of WebView2 to update.||Navigation history|
||Raised when WebView encounters a Basic HTTP Authentication request. See Basic authentication for WebView2 apps.||Authentication|
||WebView2 finishes parsing the DOM content but hasn't finished loading all images, script, and other content on the page.||Navigation events|
||WebView2 completes loading content on the new page.||Navigation events|
The diagram above shows navigation events that have the same
NavigationId property on the respective
Track navigation events to each new document by using the
NavigationId property of each navigation event's
eventArgs object. Each navigation involves a sequence of navigation events. The
NavigationId value changes every time a successful navigation to a new document is completed.
Navigation events that have different Navigation IDs may overlap. For instance, when you start a navigation event, you must wait for the related
NavigationStarting event. The
NavigationStarting event is identified by the
NavigationId property on the
NavigationStartingEventArgs object. 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 Navigation ID remains the same.
Same-document navigation events, such as navigating to a fragment in the same document, don't cause a
NavigationStarting event to be fired, and don't cause the Navigation ID to change.
Navigation in frames
To monitor or cancel navigation events inside frames in a WebView2 instance, use the equivalent frame-related APIs and events. See Using frames in WebView2 apps.
Navigation example code
For example code showing how to handle navigation events, see:
- Learn about navigation events in Get started with WebView2 in WinUI 2 (UWP) apps - no example code in the article; see other frameworks' articles.
- Step 6 - Navigation events in Get started with WebView2 in WinUI 3 (Windows App SDK) apps.
- Step 8 - Navigation events in Get started with WebView2 in WPF apps.
- Step 8 - Navigation events in Get started with WebView2 in WinForms apps.
- Step 14 - Navigation events in Get started with WebView2 in Win32 apps.
The WebView2 Sample apps also demonstrate handling navigation events.