Progressive web apps have always had an awkward installation experience. The browser may show an address-bar icon, a menu item, or a prompt at a time the developer does not control. The older beforeinstallprompt pattern gives a site more control, but it also means writing and maintaining a custom installation flow.
Two newer web-platform entry points aim to make that experience more deliberate: the browser-controlled HTML <install> element and the JavaScript navigator.install() method. They can let a site offer installation from a page—and even support an app catalog—but they do not turn installation into an ordinary download button. The browser still owns consent, manifest validation, and the final decision.
That distinction matters for both security and reliability. A page should not be able to draw a convincing “Install” control that silently installs software or misrepresents another origin. The new APIs are designed around user activation and browser-mediated UI, and they are still evolving. Treat them as progressive enhancements, not as a requirement for using your site.
What problem do the new APIs solve?
There are two separate problems:
- A product team wants an obvious install action for its own web app.
- A portal or suite wants to offer several web apps from one catalog page.
Historically, the first problem often required catching beforeinstallprompt, saving the event, and later calling its prompt() method from a custom button. The second problem was harder because installation was generally tied to the current page.
The Web Install work provides two approaches:
<install>is declarative HTML. The browser renders the control, including its label and presentation, and can render fallback child content when the feature is unavailable.navigator.install()is an imperative JavaScript API. It is useful when the product needs a custom interface, but the call must happen from a user gesture and the page must handle a rejected promise.
Both approaches still lead to browser-controlled installation consent. They are not APIs for silently adding an app to a device.
Start with a stable manifest identity
Before adding an install control, make the app manifest correct. A minimal manifest might look like this:
{
"id": "/",
"name": "Example application",
"short_name": "Example",
"start_url": "/",
"display": "standalone",
"icons": [
{
"src": "/icons/app-192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/icons/app-512.png",
"sizes": "512x512",
"type": "image/png"
}
]
}
Link it from the document:
<link rel="manifest" href="/manifest.webmanifest">
The id is more than a label. It gives the browser a stable identity separate from the launch URL. That helps prevent an app from unexpectedly becoming a different installed app when its start_url changes.
For a current-document installation, the manifest must be appropriate for that document. For a catalog that installs another app, the target manifest must also satisfy origin, HTTPS, response, and identity checks. Do not treat a manifest URL as an arbitrary file URL: it is part of the browser's application-identity and consent process.
Prefer <install> when browser-owned UI is the right trade-off
The declarative approach is intentionally small:
<install>
<a href="/about">Open the web app</a>
</install>
For a page whose linked manifest describes the current app, the element can be used without JavaScript. If the browser supports the feature, it supplies the install affordance. If it does not, the child link remains useful fallback content.
The browser controls the button's text, iconography, and much of its presentation. That limits visual customization, but the limitation is a feature: users can distinguish a browser-provided installation control from a page that merely looks like a system dialog.
The element can also be used for a catalog-style experience when the browser and proposal version support targeting another app. The exact attributes and availability are still changing, so follow the current implementation guidance rather than copying an old experiment indefinitely. The important design rule is stable target identity: the target manifest and its start_url must describe the same app origin, and a missing manifest id may require an explicitly supplied computed identity.
If you need to report outcomes, use the events and result values documented for the implementation you target. Do not assume that “success” means a brand-new installation: the browser may instead open an app that is already installed. A page should report the user-visible result accurately, not claim that it can distinguish every browser decision.
Use navigator.install() only from a real user action
Custom UI is sometimes necessary. A large app catalog, an existing design system, or a flow that combines install with other product context may not fit a browser-rendered control. The imperative API can be feature-detected and called from a button:
<button id="install-app" type="button" hidden>Install app</button>
<p id="install-status" role="status"></p>
<script type="module">
const button = document.querySelector("#install-app");
const status = document.querySelector("#install-status");
if (typeof Navigator.prototype.install === "function") {
button.hidden = false;
}
button.addEventListener("click", async () => {
button.setAttribute("aria-disabled", "true");
try {
await navigator.install();
status.textContent = "The app was installed or opened.";
button.hidden = true;
} catch (error) {
if (error instanceof DOMException && error.name === "AbortError") {
status.textContent = "Installation was canceled or unavailable.";
} else {
status.textContent = "Installation could not start.";
console.error(error);
}
} finally {
button.removeAttribute("aria-disabled");
}
});
</script>
This example is a documented pattern to adapt, not a claim that it was run in every browser. The feature must be available in the target browser, the page must be in a suitable secure context, and the call must remain inside the click handler. Delaying the call through an unrelated asynchronous step can lose the transient user activation that proves the user initiated the operation.
The error path is part of the feature, not optional polish. A user can cancel. A manifest can be invalid. A permission policy or sandbox can block installation. An already-running install attempt or a navigation can also prevent completion. Keep the button retryable after an expected cancellation, and surface unexpected failures to developers rather than hiding them behind a success message.
Cross-origin installation is not a shortcut around trust
An app catalog may want to install an app hosted at another origin. The API documentation describes constraints for that case, including:
- The target manifest must be fetched over HTTPS.
- The manifest must be reachable without credentials or redirects.
- The response must use a JSON manifest content type.
- The manifest's
start_urland manifest URL must share the target app's origin. - A stable
idis preferred; if it is absent, the caller must provide the processed manifest identity where the API requires it.
These rules prevent a catalog page from casually presenting one origin while installing an ambiguous or changing application identity. They also mean that a catalog should validate its own inventory before showing an install action. A broken manifest should produce a disabled or explanatory state, not a button that fails only after a user click.
Do not imitate the browser-owned control with CSS or place a custom button over it. If the browser controls the affordance, that presentation is part of the security model. If you choose the JavaScript API instead, make the page's branding and the browser's consent dialog clearly distinguishable.
Progressive enhancement is the compatibility strategy
The new APIs are not a reason to block users who cannot install a PWA. A robust page should work in these layers:
- Core website: navigation and primary functionality work without installation.
- Manifest enhancement: browsers that support web app installation can offer their normal install UI.
- Declarative enhancement: use
<install>when the browser supports it, with useful child fallback content. - Imperative enhancement: use
navigator.install()only when feature detection succeeds and custom UI adds real value. - Legacy fallback: retain the established
beforeinstallpromptflow or explain the browser's manual install steps where appropriate.
Keep the install button hidden until the selected mechanism is available. Avoid promising “one-click install” when the browser still requires a consent dialog, or when the feature is restricted to a flag, an origin trial, or a limited browser release. Availability should be checked against current browser documentation at deployment time.
Accessibility also belongs in the fallback design. A browser-owned control may have its own semantics; custom UI still needs a real button, an accessible status message, visible focus, and a useful response after cancellation. A user who declines installation should be able to continue using the site normally.
A practical adoption checklist
Before experimenting with these APIs:
- Give the app manifest a stable, intentional
id. - Serve the manifest and installation page over HTTPS.
- Verify the manifest response, MIME type, icons, and
start_url. - Feature-detect the exact API or element you plan to use.
- Keep
navigator.install()directly in a trusted user-activation handler. - Treat cancellation and unsupported environments as normal outcomes.
- Provide fallback content or a normal link for unsupported browsers.
- Test target-browser behavior using the current official documentation and any required origin-trial or flag instructions.
- Never claim that a resolved promise proves a new installation occurred.
- Do not collect unnecessary device or identity data around an install action.
The most trustworthy install experience is not the one with the most persuasive button. It is the one that makes the app identity clear, lets the browser own consent, works without installation, and reports uncertainty honestly.