This is an archived page. It's not actively maintained.

Firefox UI considerations for web developers

There are a number of places within the Firefox user interface where web sites are listed for the user to choose a destination to visit or a site to manage in some way. One example is the new tab page, which includes a "Top Sites" section showing sites you visit that Firefox thinks you're likely to want to visit again, as well as potentially some sites that have been pinned to always appear in that space.

Firefox's Top Sites box

Screenshot showing what the Firefox Top Sites box looks like

In this article, we take a look at how to influence the appearance of your site in Firefox user interface elements such as the Top Sites box.

Top Sites

The Top Sites box lists a user-configurable number of rows of icons serving as quick links to sites the user commonly visits, or that the user has chosen to pin to the Top Sites list in order to have quick access to them.

Each site is represented by an icon and, below it, a name for the site. While both of these can be edited by the user, you may wish to ensure that your site provides a good icon to use in places like this.

How an icon is selected

The new tab page chooses icons to use for top sites by trying a series of methods until it obtains an icon to use:

  1. A global "top sites" list is checked. This list is created by a Mozilla service called Tippy Top. The data store provided by Tippy Top includes an optimized icon for each of the sites in the list; if the site is on this list, that icon is used.
  2. If Tippy Top doesn't include the site, Firefox looks in its Places data store for icons specified in the page's <head> element;
    1. If an SVG icon is available, that icon is selected.
    2. Otherwise, bitmapped icons which are at least 96 pixels wide are considered. If one is found to have a width of exactly 96 pixels, it is used. Otherwise, the smallest image larger than 96 pixels wide is selected.
    3. If no high-resolution icon is found, a screenshot is taken of the site; this screenshot is then scaled and cropped to fit in the space allotted to the icon. If the site also has a favicon, it may be overlaid in the corner of the image.

The selected image is then presented within the Top Sites list.

Rich icons

The high resolution icons—also known as rich icons—are specified by setting the rel attribute to one of:

  • apple-touch-icon
  • apple-touch-icon-precomposed
  • fluid-icon

The size of each icon is taken from the size attribute specified on the <link>, if it's provided. apple-touch-icon and apple-touch-icon-precomposed icons with no size attribute are assumed to be the standard classic iPhone size of 57x57 pixels.

The icon closest in size to 96 pixels is selected. Firefox does its best to avoid having to scale the images, which can result in fuzzy or distorted images, especially at smaller sizes.

Providing a Top Sites ready icon

The simple rule is to provide an icon which is at least 96x96 pixels in size, using a <link> element whose rel attribute is a reference to a file containing an icon of a supported type.

<link rel="apple-touch-icon" sizes="128x128" href="touch-icon-128x128.png">
<link rel="apple-touch-icon" sizes="46x46" href="touch-icon-46x46.png">
<link rel="apple-touch-icon" sizes="256x256" href="touch-icon-256x256.png">
<link rel="icon" href="favicon.ico">

In this code, the 128x128 pixel icon will be used by Firefox, as it's the smallest icon which is larger than the 96-pixel size it requires.

Note: Only "rich" icons (apple-touch-icon and fluid-icon) support the sizes attribute. You can't specify the size for rel="icon" using the sizes attribute.


Consider again the example Top Sites box shown at the top of the page, repeated below:

Let's look at some examples among the icons shown here (note that this discussion is based on the site designs as of early January, 2019).

USA Today

The only icon provided by USA Today is its classic favicon:

<link rel="shortcut icon" href="">

Since no rich icon is available, Firefox creates a screenshot of the home page rendered 560 pixels wide. The screenshot is then drawn in the icon box, which scales and crops the image as needed to fit. The favicon is rendered in a small box in the lower-right corner of the icon box to further identify the site.


The HTML on Hootsuite's site looks roughly like this:

<link rel="shortcut icon" href="/dist/images/icons/favicon.ico">
<link rel="apple-touch-icon-precomposed" href="/dist/images/icons/apple-touch-icon.png">
<link rel="apple-touch-icon-precomposed" sizes="72x72" href="/dist/images/icons/apple-touch-icon_72.png">
<link rel="apple-touch-icon-precomposed" sizes="114x114" href="/dist/images/icons/apple-touch-icon@2x.png">

Firefox starts by looking for an SVG icon; there is none. So it then goes on to look through the rich icons. Here, there are three of them, each specified as apple-touch-icon-precomposed. Since none of them are 96 pixels wide, the smallest icon which is at least 96 pixels wide is chosen; that's the 114x114 pixel apple-touch-icon@2x.png file.

That image is then scaled down to be 96 pixels wide and is used in the user interface as seen in the example.