Gecko basics

While the core of Firefox is written in C++, the front-end code is itself written in JavaScript. This JavaScript code, which is commonly referred to as chrome code, runs with system privileges.

This article provides a basic primer on the main objects available to chrome code.

Browser window

At the top level, there's the browser window. It represents a top-level Firefox application window, including all the toolbars, menus, and so on, as well as all the tabs that contain web pages. JavaScript running in the browser window context is system-privileged chrome code.

Firefox specifies its interface using a markup language called XUL. So when the browser application opens a browser window, it loads and renders a particular XUL file, which came bundled with the application. XUL files are loaded using a special URL scheme called "chrome://" ("Chrome" is the informal name given to the parts of the browser that provide the UI -- toolbars, menus, and so on).

The XUL file that specifies the Firefox user interface is loaded from "chrome://browser/content/browser.xul". You can paste that URL into the Firefox address bar, and you'll see another fully-functional copy of the Firefox user interface in the place you normally see a web page.

For these reasons, a browser window is also sometimes called a "XUL window" or a "chrome window". To JavaScript code it's of type ChromeWindow.


The browser window has a property gBrowser, which is a XUL tabbrowser object. This contains all the tabs that the user has opened in this application window.

XUL browsers

Each tab contains a single XUL browser object, which represents a single browsing context (typically, a single document the user's viewing, but also extras like the history for that tab). There's a DOM Window associated with each browser, and an HTML Document loaded into that DOM window.

Chrome and content

Between the XUL browser and the DOM window is the boundary between chrome and content. Objects in the content side are loaded from the Web as HTML, JavaScript, CSS, and so on. JavaScript running in this context is untrusted and is called "content code". The global for such JavaScript is usually its DOM window.

Objects in the chrome side are part of Firefox itself, either part of the built-in browser or browser extensions. Code running in the chrome side is system privileged and it called "chrome code". Its global is usually the browser window.

In multiprocess Firefox, chrome code and content code run in different processes (note that this isn't quite true: in multiprocess Firefox, frame scripts are given most of the privileges of chrome code, but run in the content process).

Chrome code

You can run JavaScript in the context of a browser window, just as you can run scripts in normal web pages. In fact, this is how the browser's front end is implemented, and how extensions are able to modify the browser's UI and behavior. This code is called "chrome code" and is system-privileged.

The simplest way to experiment with running chrome code is using the Browser Console. Open the Browser Console, enable chrome debugging, and type:


In response, you should see:

ChromeWindow ā†’ chrome://browser/content/browser.xul

That's telling us that we're running in chrome context. You should be able to examine all the other properties of the browser window:

<<    window.gBrowser
>>    <tabbrowser...>
<<    window.Components
>>    nsXPCComponents { utils: nsXPCComponents_Utils,... }

// more on:

// - privileged APIs available to chrome code: XPCOM, JSMs, other Components stuff, SDK modules, gDevTools, and how to access them

// working with content: Xray vision, e10s