Edit

Navigation events for WebView2 apps

  • Article

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, NavigationCompleted runs.

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:

WebView2 Navigation Events

Sequence Event Description API Reference overview
1 NavigationStarting WebView2 starts to navigate and the navigation results in a network request. The host may disallow the request during the event. Block unwanted navigating
2 SourceChanged 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
3 ContentLoading WebView2 starts loading content for the new page. Navigation events
4 HistoryChanged The navigation causes the history of WebView2 to update. Navigation history
5 BasicAuthenticationRequested Raised when WebView encounters a Basic HTTP Authentication request. See Basic authentication for WebView2 apps. Authentication
6 DOMContentLoaded WebView2 finishes parsing the DOM content but hasn't finished loading all images, script, and other content on the page. Navigation events
7 NavigationCompleted 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 eventArgs object.

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:

  1. The NavigationStarting event for the first navigation.
  2. The NavigationStarting event for the second navigation.
  3. The NavigationCompleted event for the first navigation.
  4. 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.

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.

For example code showing how to handle navigation events, see:

The WebView2 Sample apps also demonstrate handling navigation events.

See also