window.browser

Draft Community Group Report,

More details about this document
This version:
https://w3c.github.io/webextensions/specification/window.browser.html
Issue Tracking:
GitHub
Editor:
(Google)

Copyright © 2025 the Contributors to the window.browser Specification, published by the WebExtensions Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

Abstract

This specification reserves the window.browser namespace for use by WebExtensions.

Status of this document

This specification was published by the WebExtensions Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

Introduction

This section is non-normative.

Browser extensions are programs to extend the capabilities of web browsers. Although not standardized at first, web browsers have independently implemented a common interoperable set of extension APIs, called WebExtensions.

Modern WebExtensions are an evolution of a system originally introduced in Chromium. In that system, any API that was added was put under the chrome namespace. When WebExtensions were adopted outside of Chromium, other vendors used the more neutral browser namespace. That browser is now considered the canonically correct namespace for all WebExtension APIs. Some interactions with WebExtensions (such as external messaging from websites to background processes) necessitate the exposure of this namespace to the web.

Given that, this document defines window.browser as reserved for the use of APIs designed to interact with WebExtensions. The specifics of what APIs within window.browser are at present intentionally undefined, and are left up to User Agent implementation.

window.browser API

browser is UA defined attribute exposed on window. When implemented, it MUST be used only for WebExtension related functionality.

For backwards compatibility with older versions of WebExtensions that used chrome as a global identifier for WebExtension related methods, a UA MAY define a global chrome object that includes all properties of browser. browser and chrome MAY be direct aliases of each other. When browser and chrome are distinct objects, each initial property of browser SHOULD be defined on the chrome object, and each property descriptor on the chrome object SHOULD return the same value as the corresponding property on the browser object.
Here’s an example of the expected alias behavior 
// When `chrome` and `browser` are not direct aliases,
// modifying one top level values will not change the other:

globalThis.browser.FAKE = true
console.log(globalThis.chrome.FAKE);
// ^ undefined when chrome and browser are not direct aliases.
// ^ may be true if browser === chrome.

// Individual properties are aliased, so updating a known property
// directly changes the matching property on the other
globalThis.browser.runtime.FAKE = 123

console.log(globalThis.chrome.runtime.FAKE);
// 123

partial interface Window {
 attribute object browser;
};

Worker API

When browser is defined on window, it SHOULD also be exposed on ServiceWorkerGlobalScope of origins associated with WebExtensions. It MUST be used exclusively for WebExtension purposes, however the contents of each instance of browser is UA defined.

partial interface ServiceWorkerGlobalScope {
  attribute object browser;
};

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[SERVICE-WORKERS]
Jake Archibald; Marijn Kruisselbrink. Service Workers. URL: https://w3c.github.io/ServiceWorker/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/

IDL Index

partial interface Window {
 attribute object browser;
};


partial interface ServiceWorkerGlobalScope {
  attribute object browser;
};