Window Shape API

at a glance

why it exists

Chrome Apps are deprecated. Virtual Desktop Infrastructure (VDI) partners that built Chrome Apps are migrating to Isolated Web Apps, and they need capabilities the standard web platform does not offer — among them custom window shapes for floating overlays and widgets. Chrome Apps provided this through chrome.app.window.setShape([rects]); the Window Shape API ports that exact capability — same signature shape, same rectangle-union behavior — so partners can migrate with minimal changes to their window-management logic.

The Chrome team is explicit that this is not a candidate for the interoperable web: the explainer argues the VDI use cases are better served long-term by more specific APIs (for example, a dedicated floating-window API) than by general window-shape masking, and the allowlist exists to prevent widespread adoption of an API with no standardization path. The intent thread records the debate: Alex Russell objected to baking a chromeos namespace and this masking model into the platform and marked the entry “needs work”; the owners resolved it by documenting scope considerations and alternatives in the explainer, and the feature shipped with LGTM1 (Chris Harrelson), LGTM2 (Mike Taylor), and an IWA-owner LGTM (Reilly Grant) on the basis that a Blink extension visible only to allowlisted IWAs “doesn’t set a new precedent”.

API entry points

All ChromeOS-specific web APIs hang off a single namespace attribute on Window. The full interface chain (verbatim from the specification):

partial interface Window {
  [Replaceable] readonly attribute ChromeOS chromeos;
};

[Exposed=Window]
interface ChromeOS {
  readonly attribute IsolatedWebApp isolatedWebApp;
};

[Exposed=Window]
interface IsolatedWebApp {};

// Window Shape API extension:
partial interface IsolatedWebApp {
  Promise<undefined> setShape(sequence<DOMRectReadOnly> rects);
};

Syntax

The feature adds one method to the IsolatedWebApp interface (full reference: setShape()):

partial interface IsolatedWebApp {
  Promise<undefined> setShape(sequence<DOMRectReadOnly> rects);
};

rects is a list of rectangles in Device Independent Pixels (DIPs) in the local coordinate space of the OS window. The window’s visible and interactive area becomes the union of those rectangles — anything outside every rectangle is not rendered and cannot be clicked. Passing an empty array resets the window to its default rectangular shape.

coordinate space and scaling

Examples

Set a two-rectangle overlapping shape, then reset it (the explainer’s canonical example):

// Set a window shape consisting of two overlapping rectangles.
await window.chromeos.isolatedWebApp.setShape([
  new DOMRect(0, 0, 200, 200),
  new DOMRect(180, 190, 100, 300),
]);

// Clear the custom shape (reset to default rectangular window).
await window.chromeos.isolatedWebApp.setShape([]);

Feature detection and guarded call (the pattern used by the official demo IWA):

const iwa = window.chromeos?.isolatedWebApp;
if (iwa && typeof iwa.setShape === "function") {
  try {
    await iwa.setShape(shapeRects);
  } catch (e) {
    console.error("setShape error:", e);
  }
} else {
  // Not an allowlisted IWA on ChromeOS — hide shape-dependent UI.
}

A complete, installable IWA demonstrating setShape with the Window Management API — including the out-of-bounds popups/tooltips pattern and a static-vs-dynamic buffer toggle — is maintained at github.com/paulinagacek/Set-Shape-demo; its TypeScript declarations match the specification IDL above.

web platform tests

There is no WPT coverage for this API. The Intent to Ship answers “Is this feature fully tested by web-platform-tests?” with “No”, and no chromeos/, isolated-web-app/, or window-shape/ directory exists in the web-platform-tests repository (repository tree checked 2026-07-28). This is consistent with the feature’s positioning: a ChromeOS-only Blink extension with no cross-browser interoperability goal.

browser compatibility

Interim table. There is no BCD entry (BCD api/Window.json contains no chromeos member, verified 2026-07-28) and no web-features entry (webstatus.dev query, zero matches). Rows below are compiled from the linked primary sources, not from BCD.

security and privacy

• Invisible or tiny windows. A shaped window could be made effectively hidden to act without the user’s knowledge. Mitigation: every shape must contain at least one rectangle of at least 10×10 DIPs; smaller rectangles alone are rejected (see exceptions).
• Clickjacking by occlusion. A shaped (for example donut-shaped) window can partially occlude another application and trick users into clicking the wrong UI. Mitigations: allowlist restriction and the required window-management permission grant.
• Allowlist as the primary boundary. Only vetted origins can call the API at all — window.chromeos is null everywhere else — so ordinary web content has no path to the capability. Enterprise administrators can further control availability with the existing window-management policies DefaultWindowManagementSetting, WindowManagementAllowedForUrls, and WindowManagementBlockedForUrls (the last forces removal of any custom shape and fallback to another display mode).
• No standardization surface. The chromeos.isolatedWebApp namespace deliberately signals embedder-specific, non-standard API so it cannot be mistaken for (or become) a web-platform contract.

specifications

see also

• IsolatedWebApp.setShape() reference — parameters, validation, exceptions, and the full application algorithm
• Unframed display mode for Isolated Web Apps — the sibling Chrome 152 feature that is a prerequisite for this API
• Chrome Platform Status — Window Shape API (API record)
• blink-dev — Intent to Ship: Window shape API
• Set-Shape-demo — official demo IWA (TypeScript)
• chromeos.dev — Isolated Web Apps
• Chrome Platform Showcase — interactive demos for this feature