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:configand enable thedom.webcomponents.enabledpref. - 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):
<link rel="stylesheet" type="text/css" href="bower_components/gaia-fonts/style.css"></link>
Firefox OS Building Blocks
- Action menu
- An action menu presents a list of actions, related to the app's content, from which the user may make a selection.
- Banners
- Banners (Status, in older versions of Firefox OS) provide information to the user in a transitory fashion, typically to confirm an action or to alert the user to a system event.
- Buttons
- Buttons are used to perform explicit actions. Buttons may be text or images.
- Context menu
- 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.
- Dialog
- 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.
- Drawer
- The drawer is a scalable way for users to navigate between views or filter views. The drawer can also include links to app settings or other tools.
- Header
- A header is a dedicated space at the top of the screen, most often used to display the view title. It can also include navigation, action buttons and other controls.
- Input area
- An input area is a data entry field, and can be as simple as a text only entry field, or as complex as a multipart entry field with text entry, value selections, and buttons.
- Layout
- The Layout utility will help you to create common layout structures for your Firefox OS apps. Note that Layout is only available in Firefox OS 2.1 and above.
- List items
- List items are typically used to navigate to a new screen, or to display information or controls.
- Picker
- The Picker is designed to select a group of items as attachments for messaging and email.
- Progress and activity
- Progress and activity indicators provide the user with visual feedback that a process (such as a resource loading) is active.
- Scrolling
- Scrolling areas allow the user to move text and/or images across the device's display.
- Search
- Search is used to filter a list or find context-specific content.
- Slider
- A Slider (which was called Seekbar in older Firefox OS versions) is used to select a value from a continuous or discrete range of values by dragging the handle.
- Select mode
- Select Mode (which was called Edit Mode in older Firefox OS versions) is designed to select and perform actions on items.
- Subheader
- Subheaders are used to describe a subsection of content.
- Switches
- Switches (such as checkboxes, etc.) allow users to activate and deactivate items. Switches are also used to select items within a list.
- Tab/Filter
- A Tab/Filter gives the user a way to easily switch between views or to filter a set of data.
- Toolbars
- Toolbars contain actions, indicators and navigation elements associated with the current view.
- Value selector
- 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.
- Firefox OS 2.3 Web components
- Firefox OS 2.0 building blocks (covers Firefox OS 2.0–2.2.)
- Firefox OS 1.x building blocks (covers older versions of Firefox OS.)