DisplayOverrideEntryObject

Syntax

A display_override entry is either a display modes list value (a string, extensions like unframed included) or a DisplayOverrideEntryObject. The spec defines the object verbatim as “an ordered map with the following members”:

"display_override": [
  {
    "display": "unframed",
    "url_patterns": [
      "/some/path/*",
      { "pathname": "/some/other/path/*" }
    ]
  }
]

Each URL pattern may be a string (parsed relative to the manifest URL, per URL Pattern string semantics) or an object with component members such as pathname. The set of accepted patterns “is restricted to exclude patterns containing regular expressions” — a deliberate security choice that follows the service worker router rules.

Inputs

Outputs

The entry participates in determining the chosen display mode, which the spec extends to take an optional document URL. The algorithm, quoted from the spec:

1. For each entry of the manifest's display_override member: let candidate display mode be null.
2. If the entry is a display mode (string): set candidate display mode to the entry.
3. Else if the entry is a DisplayOverrideEntryObject: if its url_patterns is empty, set candidate display mode to the entry's display; else if the document URL is not null, for each pattern of url_patterns: if the pattern matches the document URL, set candidate display mode to the entry's display and break.
4. If candidate display mode is null, continue to the next entry.
5. If the display modes list contains the candidate, return it. (For extensions, the spec adds per-mode gates: unframed is returned only “if the user agent supports this, and the application is an Isolated Web Application”.)

The observable output is the window's display mode: the first entry in the fallback chain that both matches the window's URL and is usable wins; matching windows open in unframed mode, non-matching windows fall through to later entries (mixing framed and unframed windows in one app).

Errors

Context and exposure

• The object form is valid only inside the manifest's display_override list — there is no JavaScript surface.
• The mechanism “is not specific to the new unframed display mode; the same idea can be leveraged by other display modes where it makes sense” (explainer). It builds on the earlier display-override proposal.
• Choosing unframed still requires the surrounding unframed prerequisites — IWA package and the window-management permission; see the overview requirements.
• Matching runs against the window's document URL — for an IWA that is an isolated-app:// URL — at window creation.

Lifecycle

1. Manifest processing (install/update): each object entry is converted to a processed override object (display, plus url_patterns when present and a list); malformed entries are skipped.
2. Window creation: the chosen-display-mode algorithm runs with the new window's document URL; a matching unframed entry makes the window open unframed “from the very beginning without flicker”.
3. Fixed thereafter: the decision is made once per window. Later navigations or history.pushState()/window.location URL changes do not re-evaluate the patterns — the window keeps the mode it was created with for its whole lifetime.

Examples

The explainer's canonical example — unframed only under two path subtrees, everything else standalone:

{
  // 1. Request the window-management permission policy.
  "permissions_policy": { "window-management": ["self"] },
  "display": "standalone",
  // 2. Add a JSON object to the display_override list.
  "display_override": [
    {
      // 3. Set display to unframed in the object.
      "display": "unframed",
      // 4. Set url_patterns to the URLs intended to be unframed.
      "url_patterns": [
        "/some/path/*",
        { "pathname": "/some/other/path/*" }
      ]
    }
  ]
}

With this manifest: a window opened at /some/path/chat is created unframed; a window at /settings matches no pattern, so the chain falls through to "display": "standalone" and opens as a normal standalone window — the “mix regular windows alongside unframed windows” goal.

Browser compatibility

Interim table. No BCD or web-features entry covers DisplayOverrideEntryObject (2026-07-28), so the rows below are compiled from the linked primary sources; shipping status follows the parent feature.

Full analysis and evidence links: overview — browser compatibility.

Security and privacy

• No regular expressions — the accepted pattern set “is restricted to exclude patterns containing regular expressions. This avoids security concerns and follows other specs like service worker routes” (explainer), keeping matching cheap, predictable, and reviewable.
• Scope is inherent — patterns are evaluated inside one IWA's own package; they cannot affect other origins (an unframed window cannot navigate cross-origin at all — see the overview lifecycle).
• The unframed spoofing analysis and its mitigations are on the overview security section.