Sub apps

at a glance

why it exists

An installed IWA can contain several applications, but a single launcher identity obscures them. The Sub Apps explainer's use cases include an office suite with separate email, document, and spreadsheet entry points that share one bundle and storage, and a virtual-desktop portal that gives streamed apps (such as a terminal and editor) their own launcher icons and windows. Sub apps provide those distinct OS entry points under one parent installation, instead of requiring separate heavyweight IWAs or one indistinguishable app window.

Syntax

The API hangs off Window as a single read-only attribute returning a SubApps instance with three asynchronous batch methods. IDL from the WICG draft:

[Exposed=Window, SecureContext, IsolatedContext]
partial interface Window {
  [SameObject] readonly attribute SubApps subApps;
};

// Represents the https://w3c.github.io/manifest/#id-member
typedef USVString ManifestId;

dictionary SubAppsAddResponse {
  record<USVString, ManifestId> installedApps;
  record<USVString, DOMException> failedApps;
};

dictionary SubAppsRemoveResponse {
  sequence<ManifestId> removedApps;
  record<USVString, DOMException> failedApps;
};

dictionary SubAppsListResult {
  required DOMString appName;
};

[Exposed=Window, SecureContext, IsolatedContext]
interface SubApps {
  Promise<SubAppsAddResponse> add(sequence<USVString> install_paths);
  Promise<SubAppsRemoveResponse> remove(sequence<ManifestId> manifest_ids);
  Promise<record<USVString, SubAppsListResult>> list();
};

add(install_paths)

Installs a batch of sub apps. Each install path is a relative URL (it must start with /) to the sub app's entry index.html, which must reference a web manifest. A single system prompt lists every requested sub app in one dialog (scrollable when batched).

remove(manifest_ids)

Uninstalls a batch of previously installed sub apps, identified by the ManifestId values returned from add() or list().

list()

Returns the sub apps currently installed under this parent IWA as a record keyed by ManifestId, so dictionary lookups (e.g. membership checks) work directly on the result. Each value is a SubAppsListResult whose appName is the name from the sub app's web manifest.

Sub app identity, resources, and limits

A sub app is not a separate security principal. It shares the parent IWA's origin, SignedWebBundleId, cookies, IndexedDB, localStorage, Cache Storage, and all granted permissions — the same-origin policy treats parent and sub apps as one entity. What distinguishes a sub app is its presentation and OS integration:

Sub-app manifests can carry their own OS integrations — protocol_handlers, file_handlers, and launch_handler act per sub app. Resources can be provisioned statically (bundled in the parent IWA, updated when the parent updates) or dynamically (a service worker serves the sub app's HTML and manifest, so sub apps update without a parent bundle update).

Two platform quotas guard against launcher flooding: at most 50 installed sub apps per parent IWA, and at most 20 sub apps per installation prompt. Exceeding either rejects the whole add() call with QuotaExceededError.

Enterprise policies

Three Chrome enterprise policies govern whether sub-app installs require a user prompt:

Each policy is expanded below from the definition the Chrome Enterprise policy list publishes for it (policy ids 1448, 1449, 1450). Three facts are common to all three: they are defined for ChromeOS 150 and later only (supported_on: chrome_os:150-), they are per profile, and they support dynamic policy refresh, so a changed value applies without a browser restart. Precedence is fixed by the definitions: SubAppsWithoutPromptsBlockedForOrigins overrides SubAppsWithoutPromptsAllowedForOrigins, which overrides DefaultSubAppsWithoutPromptsSetting — so an origin listed in both lists is never prompt-free. The examples below are the managed-policy JSON form of each definition's own published example_value; the definitions publish a value domain and an example value but no per-platform deployment path, so none is claimed here.

DefaultSubAppsWithoutPromptsSetting

Caption from the definition: “Control use of the Sub Apps Add API”. This is the global default for whether an IWA origin may add sub apps at all, and whether the confirmation prompt described at add(install_paths) is shown.

// Managed-policy JSON form of the published example_value (3)
{ "DefaultSubAppsWithoutPromptsSetting": 3 }   // AskSubApps  - prompt the user (same as unset)
{ "DefaultSubAppsWithoutPromptsSetting": 1 }   // AllowSubApps - prompt-free for every IWA origin
{ "DefaultSubAppsWithoutPromptsSetting": 2 }   // BlockSubApps - IWA origins cannot add sub apps

SubAppsWithoutPromptsAllowedForOrigins

Caption from the definition: “Allow Isolated Web Apps to use Sub Apps Add API without user prompt”. The definition states that by default IWA origins can add sub apps provided the user confirms the prompt interactively, and that this policy controls which IWA origins may add sub apps without the user being prompted.

// Managed-policy JSON form of the definition's own published example_value
{
  "SubAppsWithoutPromptsAllowedForOrigins": [
    "isolated-app://egoxo6biqdjrk62rman4vvr5cbq2ozsyydig7jmdxcmohdob2ecaaaic",
    "isolated-app://anayaszofsyqapbofoli7ljxoxkp32qkothweire2o6t7xy6taz6oaacai"
  ]
}

SubAppsWithoutPromptsBlockedForOrigins

Caption from the definition: “Block Isolated Web Apps from using Sub Apps Add API without user prompt”. It controls which IWA origins are blocked from adding sub apps without the user being prompted interactively — the deciding policy wherever it overlaps the other two.

// Managed-policy JSON form of the definition's own published example_value
{
  "SubAppsWithoutPromptsBlockedForOrigins": [
    "isolated-app://egoxo6biqdjrk62rman4vvr5cbq2ozsyydig7jmdxcmohdob2ecaaaic",
    "isolated-app://anayaszofsyqapbofoli7ljxoxkp32qkothweire2o6t7xy6taz6oaacai"
  ]
}

Examples

// Inside an installed IWA with Permissions-Policy: sub-apps=(self)
const { installedApps, failedApps } = await window.subApps.add(["/calc/", "/docs/"]);

for (const [installPath, manifestId] of Object.entries(installedApps)) {
  console.log(`installed: ${installPath} -> ${manifestId}`);
}
for (const [installPath, exception] of Object.entries(failedApps)) {
  console.error(`failed: ${installPath} — ${exception.name}`);
}

// Later: enumerate and remove. The second id is deliberately not one of this
// parent IWA's sub apps, so the response shows BOTH of its members: removedApps
// for the ids it uninstalled, failedApps for the ids it could not (NotFoundError).
const all = await window.subApps.list();          // record<ManifestId, { appName }>
const calcId = Object.keys(all).find((id) => all[id].appName === "Calculator");
if (calcId) {
  const { removedApps, failedApps: notRemoved } =
    await window.subApps.remove([calcId, "stale-manifest-id"]);
  console.log("removed:", removedApps);
  for (const [manifestId, exception] of Object.entries(notRemoved)) {
    console.error(`not removed: ${manifestId} — ${exception.name}`);
  }
}

Browser compatibility

There is no browser-compat-data (BCD) entry for this API yet, so the table below is an interim view built from ChromeStatus ship data and public vendor signals — not from BCD.

Specifications

See also

• WICG — Sub Apps explainer
• Sample sub-apps demo (static and service-worker-provisioned)
• WICG proposal — Sub Apps
• Isolated Web Apps on chromeos.dev
• W3C TAG — does not review Isolated Web Apps
• Chrome Platform Showcase — Sub apps (also: manifest-id round trip, install response map)