Published: August 19, 2025
Navigation management encompasses the methods for controlling how a Progressive Web App (PWA) handles user navigation. A critical component of this is navigation capturing, the browser process that determines whether clicking a link should launch the installed PWA or open a new browser tab.
This guide covers the new version of navigation capturing, available from Chrome 139. While the browser's default behavior is suitable for most cases, a deeper understanding of these management techniques and their related APIs is essential if you want to create the smoothest experience for your users.
The Developer controls section shares how to customize navigation to deliver the best possible launching experience for your PWA.
The new default behavior
To align with user preferences and reduce friction, Chrome is standardizing how it handles links. Previously, the behavior was inconsistent across platforms. Mobile devices typically prioritized launching installed apps, while desktop browsers would first open a link in a tab before signaling that an app could handle it.
The new, unified approach for navigation capturing, automatically opens links in their corresponding installed PWA. Links will only fall back to a browser tab if the PWA isn't installed or if the user has opted out. This new behavior is available from Chrome 139 for Windows, Mac, and Linux, with ChromeOS support coming in a future release.
The navigation management process
Navigation capturing is part of the navigation management process. This process covers the entire flow, from the user's initial action to the browser's decisions and the resulting behaviors configured by the developer:
- User actions: Includes interactions such as clicking or tapping on links.
- Browser decisions: includes tasks and decisions managed by the browser, such as default behaviors, like navigation capturing.
- Developer controls: Includes web APIs that let developers instruct the browser on how to handle specific tasks.
The interplay of these elements determines whether the PWA opens in a standalone window or a browser tab.
A fundamental navigation management use case is when a user clicks or taps a link to the installed PWA from another page in the browser. The following example walks through the case of a user that has installed the Google Chat PWA and clicks on a link to it from a Google Calendar invite.
calendar.google.com.User actions
Every user action consists of three key elements: the event (such as a click
or tap), the surface where it takes place (like a webpage or desktop
shortcut), and the link type being activated (like an HTTPS URL). For example,
a user's action could be clicking a link to
https://chat.google.com/meeting_room_id within the scope of the Google Chat
PWA from a webpage on calendar.google.com.
Browser decisions
Upon a user action, like the user clicking in the previous step, the browser runs the navigation capturing process to decide whether links should be open in a browser tab or in an installed PWA. It consists of the following steps:
- Determine if the navigation is capturable: In general, a navigation is considered capturable if it creates a new frame and does not open in an auxiliary browsing context.
- Identify a controlling PWA: If the navigation is capturable, the browser tries to find a PWA that "controls" the URL (falls within the scope defined in its Web App Manifest).
- Verify user preference: If a controlling PWA is found, the browser checks user preference. If the user hasn't opted out in the app settings, the PWA launches; otherwise, the link opens in a new browser tab.
- Launch the PWA: The browser launches the PWA using the Launch Handling Algorithm. You can influence this using the Launch Handler API, covered next.
The following diagram summarizes this process:
Developer controls
While the navigation process primarily relies on browser defaults and user settings, you can use various APIs to manage specific aspects of it. Following the recent navigation capturing update, some long-standing web APIs have become more relevant.
Launch Handler API
This API comes into play when the browser decides to launch the PWA, letting you control how it is launched—for example, in a new or an existing window.
Define how the PWA launches through the launch_handler member in the Web App
Manifest, which includes a subfield called client_mode. This subfield
determines whether a new or existing window should be used and whether it should
navigate. The allowed values for client_mode are:
focus-existing: To handle the link in an existing app window, like a PWA that is already running in standalone mode.navigate-existing: In this option the most recently interacted with, browsing context in a web app window is navigated to the launch's target URL.navigate-new: With this option a new browsing context is created in a web app window to load the launch's target URL.
Use the launchQueue API to provide additional parameters and handle special
cases.
The Launch Handler API is available from Chrome 110, but becomes much more
useful with the navigation capturing update. You can learn more about it in
the Launch Handler API documentation.
Other related APIs
Besides launch handling, other APIs can also play a role in this process,
depending on your app's specific needs. These include
URL Protocol Handlers,
which allow a web app to register its ability to handle URL schemes beyond the
standard http and https (for example, standard protocols like mailto: or
custom ones like web+music). Also, the
Web App Scope Extensions API (currently
under development) lets you extend the scope of your PWA to capture links from
other origins, including subdomains, so that when a user clicks on a link from
an associated origin, the PWA can be launched. Covering them in depth is out of
the scope of this article, but you can check out the corresponding links to know
more.
Use-case: Capturing Google Chat links in the Chat PWA
To wrap up, learn how the different pieces work together in the example of clicking on a Google Calendar link to a Google Chat room, for a user that has already installed the Google Chat PWA.
Before navigation capturing
In the following video, a user creates a Google Calendar meeting and invites three guests. The Calendar app automatically generates a Google Chat link that includes all participants. When the user clicks this link, the chat room opens in a new browser tab. An icon in the address bar then signals that a corresponding PWA is installed, but it requires the user to launch it manually. This was the behavior before the navigation capturing update:
After navigation capturing
The following video shows the same user workflow, but now with the new
navigation capturing behavior. In this version, clicking the Google Chat
link from Google Calendar opens the corresponding chat room directly in the
installed PWA. Furthermore, the Google Chat team has implemented Launch Handling
by adding a launch_handler attribute to the Web App Manifest. By setting its
client_mode to focus-existing, they ensure that the link opens in an
existing instance of the PWA, if one is already running. By removing the latency
involved in opening a new browser tab and then triggering a page load, the
effective 'time to user interactivity' can be, by design, faster. In fact,
Google Chat significantly improved the navigation latency by removing the need
for a new app launch.
Conclusion and next steps
This article explored the new default navigation capturing behavior available from Chrome 139, focusing on a common use case of a user clicking an HTTPS link within the scope of an installed PWA. You can find more information and use cases in Navigation Management into Installed PWAs. The following diagram shows the full breakdown of use cases, including user events, surfaces and protocols, with their corresponding outcomes:
Navigation management is a crucial, yet often overlooked, aspect of your app's UX, as it controls its entry point. The features and links covered in this article can help you achieve the best possible app-like experience for your PWA.