Using the browser API

This translation is incomplete. Please help translate this article from English

No estándar
This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

This API is available on Firefox OS for privileged or certified applications only.


The HTML Browser API is an extension of the HTML <iframe> element that allows web apps to implement browsers or browser-like applications. This entails two major aspects:

  • Make the iframe appear like a top-level browser window to the embedded content. This means that, window.parent, window.frameElement, etc. should not reflect the frame hierarchy. Optionally, the notion that the embedded is an Open Web App can be expressed as well.
  • An API to manipulate and listen for changes to the embedded content's state.

In addition to that, it's also possible to express the notion that the embedded content is an Open Web App. In that case the content is loaded within the appropriate app context (such as permissions).


An <iframe> is turned into a browser frame by setting the mozbrowser attribute:

<iframe src="http://hostname.tld" mozbrowser>

In order to embed an Open Web App, the mozapp attribute must also be supplied, with the path to the app's manifest:

<iframe src="http://hostname.tld" mozapp='http://path/to/manifest.webapp' mozbrowser>

At last the content of the <iframe> can be loaded in its own child process, separate to the page embedding this frame by using the remote attribute.

<iframe src="http://hostname.tld" mozbrowser remote>

Warning: That last attribute is necessary for security reasons if you plan to load content from an untrusted/unknown origin. If you don't use it, you take the risk of your application being compromised by a malicious web site.


Any application that wants to embed a browser frame must have the browser permission within its app manifest.

  "permissions": {
    "browser": {}

Additionally, to embed an Open Web App, the app must have the embed-apps permission.

  "permissions": {
    "browser": {},
    "embed-apps": {}

Extra methods

To support the requirement of a browser <iframe>, Firefox OS extends the HTMLIFrameElement DOM interface. Those new methods gives the <iframe> some super powers:

Those methods allow navigating through the browsing history of the <iframe>. They are necessary to be able to implement back, forward, stop, and reload buttons.

Performance methods

Those methods are used to manage the resources used by a browser <iframe>. This is especially useful for implementing tabbed browser application.

Event methods

In order to manage the browser <iframe>'s content, many new events were added (see below). The following methods are used to deal with those events:

Miscellaneous methods

Those methods are utilities, useful for apps that host a browser <iframe>.

  • getScreenshot(): Allows taking a screenshot of the browser <iframe>'s content. This is particularly useful to get thumbnails of tabs in a tabbed browser app.
  • zoom(): Change the zoom factor of the browser <iframe>'s content. This is particularly useful to perform zoom in/out on non-touch-enabled devices.


In order to allow an application to manage the browser <iframe>, the application can listen for new events about what's happening within the browser <iframe>. The following new events can be listened for:


In this example we'll see how to implement a very basic browser app.


In the HTML we just add a URL bar, a "Go" and "Stop" button, and a browser <iframe>.

  <input id="url">
  <button id="go">Go</button>
  <button id="stop">Stop</button>

<iframe src="about:blank" mozbrowser remote></iframe>


We switch between the go and stop button with a little css trick.

button:disabled {
  display: none;


Now we can add the required functionalities:

document.addEventListener("DOMContentLoaded", function () {
  var url  = document.getElementById("url");
  var go   = document.getElementById("go");
  var stop = document.getElementById("stop");

  var browser = document.getElementsByTagName("iframe")[0];

  // This function is used to switch the Go and Stop button
  // If the browser is loading content, "Go" is disabled and "Stop" is enabled
  // Otherwise, "Go" is enabled and "Stop" is disabled
  function uiLoading(isLoading) {
      go.disabled =  isLoading;
    stop.disabled = !isLoading;

  go.addEventListener("touchend", function () {
    browser.setAttribute("src", url.value);

  stop.addEventListener("touchend", function () {

  // When the browser starts loading content, we switch the "Go" and "Stop" buttons
  browser.addEventListener('mozbrowserloadstart', function () {

  // When the browser finishes loading content, we switch back the "Go" and "Stop" buttons
  browser.addEventListener('mozbrowserloadend', function () {

  // In case of error, we also switch back the "Go" and "Stop" buttons
  browser.addEventListener('mozbrowsererror', function (event) {
    alert("Loading error: " + event.detail);

  // When a user follows a link, we make sure the new location is displayed in the address bar
  browser.addEventListener('mozbrowserlocationchange', function (event) {
    url.value = event.detail;

See also