The Firefox OS Building Blocks are reusable UI components (also called 'common controls') that reflect OS-wide design patterns. Building Blocks are used to create the interfaces of all Gaia default apps. You are free to make use of these components in your own Firefox OS apps, or general Web apps.

Using the Firefox OS Building Blocks

The code for the Firefox OS Building Blocks can be found in the Gaia Github repo under shared/style. Here, you can find a CSS file that contains the CSS for that particular Building Block, and a sub directory containing the HTML fragments and image assets. If you are creating your own standalone Web app, you can simply copy the CSS, HTML and image asset files across into your own project; if your app is intended to be installed on Firefox OS only (or you want to use these features only when the app is being used on Firefox OS), then you can link to the versions available inside Gaia.

The pages for the individual Building Block implementations can be found under the pages for each building block — see next section. These contain instructions on how to implement each one.

Note: The version 2.0 building block code is used in Firefox OS releases 2.0 through 2.2. Version 2.3 sees an update, with the building blocks being reimplemented using Web components — these provide the same functionality, but implemented in a much more powerful, flexible way. You'll see 2.3 pages appear underneath the main building block pages covering these Web components as soon as the information is available.

Note: We also have an old guide covering the v1.x building blocks used in older versions of Firefox OS. This is mainly for legacy information.

Web components preliminary setup

This section details the preliminary setup needed to use Gaia Web components.

Web components browser support

To use Gaia Web components at all, you need to run them using a browser that supports Web components. The state of support is as follows:

Firefox: Supported since Firefox 23 (33 on Android), but preffed off. To enable Web components, go to about:config and enable the dom.webcomponents.enabled pref.

Chrome: Supported since Chrome 33 (39 on Android).

Opera: Supported since Opera 20 (24 on Android).

Android browser: Supported since 4.4.4.

Safari/iOS Mobile and IE/IE mobile: Nope.

Web components are supported in Firefox OS from v2.1 onwards, although most of them weren't actually implemented until v2.3. Be aware also that currently Web components won't work for Firefox OS apps below internal (certified) level. This restriction should be lessened in the future.

Note: If your app is certified, the components will just work. You don't need to set a specific manifest permission.

Web components installation notes

Gaia Web components are installed in your app using the Bower package manager. To install this, you first need Node.js/npm and Git installed. Once they are installed you can install Bower with

npm install -g bower

At this point you could also install the Gaia Fira Sans font that Firefox OS uses in your app , with the following command:

bower install gaia-components/gaia-fonts

You can then make use of the font by including the following in your head (along with a font-family of FiraSans):

Accessed via a tap and hold gesture (sometimes called a long press), the Context Menu (called the Object Menu in older versions of Firefox OS) allows users to perform actions on objects without having to leave their current view.

A Dialog (Confirm, in older versions of Firefox OS) provides the user with some important information, asks the user to take or confirm an action, or allows the user to make a choice or enter some information.

Value Selectors let the user choose from among a list of possible values.

Note: For a detailed guide to the design pattern followed by the building blocks when the Arabic locale (bidirectional) is selected, read Firefox OS in Arabic.

Cross browser CSS

Arnau March wrote a CSS file called cross browser CSS, containing rules to allow Firefox 2.0 building blocks to render properly across different browsers (ie 9, Firefox 18, Chrome 24, Safari 5.1.) If you want to write hosted apps that look ok across different browsers, include this CSS in your project.

Browse Firefox OS Building Block implementations by version

The pages below list links to pages covering the Firefox OS Building Block implementations as they appear in different versions of Firefox OS.