←All posts

Chrome 158 Ships the Web Install API: A Native Install Button in Plain HTML

Chrome 158 launches navigator.install() and the <install> element, letting any page offer to install a web app, including one from another origin, through a browser-controlled prompt. Here is how to use both safely and what to do about the browsers that do not support it.

Chrome 158 Ships the Web Install API: A Native Install Button in Plain HTML

Installing a progressive web app has always been oddly hidden. Users had to notice a small icon in the address bar, or developers had to wire up beforeinstallprompt and hope the browser fired it. Chrome 158, planned for Stable on November 17, 2026, adds a more direct route. According to the Chrome Platform Status release notes, the Web Install API arrives as two pieces launching in parallel: the imperative navigator.install() method and the declarative <install> element.

This post covers what each one does, how to write them correctly, and how to roll them out without breaking anything for users on other browsers.

What the Web Install API actually is

Both entry points ask the browser to run its normal web app installation flow. You supply a manifest location, and optionally a manifest ID. The browser shows the prompt, and the user decides. The page cannot install anything on its own.

Two properties make it different from what came before:

  • It works across origins. One site can offer to install a web app hosted on another. A company portal can offer the installable version of a separate product, or a directory can offer apps it lists.
  • It does not depend on a browser heuristic. With beforeinstallprompt, you wait for the browser to decide the page is installable. Here, you ask.

The Chrome for Developers guide to the install element describes the browser-controlled design: the browser owns the button's label, language and appearance, so a click is a trustworthy signal of intent. For navigator.install(), user activation (a click or tap) is the equivalent signal.

The declarative route: the install element

If the current page links a manifest that has an id field, the element needs no attributes:

<install></install>

To offer an app from another origin, point at it with installurl. If that app's manifest has no id, add manifestid:

<install installurl="https://awesome-app.com/"
         manifestid="https://awesome-app.com/?source=pwa">
</install>

The computed ID is visible in DevTools under Application, then Identity, as "Computed App ID".

Content inside the element is shown when the browser does not support it, which gives you a built-in fallback:

<install installurl="https://awesome-app.com/">
  <a href="https://awesome-app.com/">Launch Awesome App</a>
</install>

Feature detection is one line:

if ('HTMLInstallElement' in window) {
  // <install> is supported
}

The element fires events you can use for analytics or UI updates. promptaction means the install succeeded, promptdismiss means the user dismissed the prompt, and validationstatuschanged lets you check e.target.invalidReason === 'install_data_invalid' when the install data is bad.

const el = document.querySelector('install');
el.addEventListener('promptaction', () => track('pwa_installed'));
el.addEventListener('promptdismiss', () => track('pwa_install_dismissed'));

The imperative route: navigator.install()

Use the method when installation is part of a flow you control, such as a button inside a custom onboarding screen. The Microsoft Edge demo shows the three call forms: no arguments to install the current document, one argument for another app's install URL, and two for the install URL plus manifest ID.

async function installApp(installUrl, manifestId) {
  if (!navigator.install) return; // not supported

  try {
    await navigator.install(installUrl, manifestId);
  } catch (err) {
    switch (err.name) {
      case 'AbortError':
        // The operation was aborted
        break;
      case 'DataError':
        // Problem with the manifest file or its ID
        break;
    }
  }
}

document.querySelector('#install-btn').addEventListener('click', () => {
  installApp('https://awesome-app.com/');
});

Call it from a click handler. Because it requires user activation, calling it on page load will not work, and it would be a poor experience even if it did.

Governance: what administrators can control

Cross-origin installation raises an obvious question about abuse, so the controls matter. Per the Intent to Ship discussion, installation needs explicit consent in browser-controlled UI, and the browser can suppress the flow. Enterprises can disable user-initiated installs with the WebAppInstallByUserEnabled policy, or control usage per origin and per iframe with the web-app-installation Permissions Policy.

If you embed third-party content that might use the API, or you ship your own iframes, it is worth checking that policy setting rather than assuming the default.

Browser support and honest caveats

This is a Chromium-led feature. The Intent to Ship thread records WebKit as opposed, on the grounds that installation is a user decision that should begin in browser UI, and Gecko as giving no signal. Treat it as progressive enhancement. The milestone details have also moved around during rollout, with earlier discussions pointing at Chrome 156 and the current release notes at 158, so confirm the status on your target browsers before you promise it to a client.

A rollout plan that holds up:

  1. Keep your existing install path (beforeinstallprompt or a plain link to the app) as the default.
  2. Add <install> with fallback content inside, so unsupported browsers see a normal link.
  3. Gate any navigator.install() call behind a feature check and a user click.
  4. Handle AbortError and DataError quietly. A dismissed prompt is not an error worth surfacing.
  5. Track promptaction and promptdismiss so you know whether the button is earning its place.

Takeaways

  • Chrome 158 adds <install> and navigator.install(), both opening the browser's own install prompt, with cross-origin support.
  • Prefer the element when a button is all you need. It needs no JavaScript and carries its fallback with it.
  • Use the method only from a user gesture, and always feature-detect.
  • Provide manifestid when the target manifest has no id, and test with the Computed App ID from DevTools.
  • Do not rely on it for cross-browser behavior yet. Build it as an enhancement over a normal link.

If your product is an installable web app, or you maintain several that should point at each other, this is a small change with an outsized effect on discoverability. We help teams ship and tune web applications like this, and a quick audit of your manifest and install flow is usually an afternoon of work.

Sources: Chrome Platform Status, Chrome 158 release notes; Chrome for Developers, install element; Microsoft Edge Web Install API demo; blink-dev Intent to Ship.

←Back to all posts
Next step

Need help shipping software?

Tell us what you're trying to build. A discovery call, a one-page summary within 48 hours, a proposal within a week.

Response · 48h·NDA on request·US contracts only