Toolbar buttons and icons in Firefox 4

Update 2: there’s a new blog post up that details the new theme rules. They’re much simpler, so I strongly recommend you use them instead of the ones detailed here, even though they still work.

Update: the resolution of bug 616472 (see comments below) may have a significant impact on this documentation. I will create a new post and link it from here if and when this bug is solved.

We have been discussing Firefox 4 add-on compatibility for quite a while, and there are a couple of pain points that are important to revisit. Nils Maier, a fellow developer, has pointed out that the changes in toolbar buttons deserve a more in-depth look than the couple of paragraphs I dedicated in my previous post. He’s right; toolbar buttons and icons in general can be a complicated issue for many developers. Those who seek to create professional-looking add-ons will most likely have to pay a professional graphics designer to work on them, and for this they need a clear specification of the icon styles and dimensions that are necessary for each platform. That is what I will cover in this post.

I created a simple demo add-on that showcases icons that work in Firefox 4 for the 3 major platforms: Windows, Mac and Linux. You can download the add-on from this link. All art is based on this simple SVN icon from the Wikimedia Commons repository.

The Add-ons Manager Icon

On Firefox 3.6 and earlier versions, the Add-ons Manager displays a 32 x 32 px icon for every installed add-on. Traditionally, this icon was defined using the iconURL tag in the install.rdf manifest. This is a chrome URL, so it has the disadvantage that it doesn’t work when the add-on is disabled, or when the install dialog for the add-on is displayed. The solution for this was to create a default location for the icon, so that it could be extracted without having to install the add-on and resolve the chrome URL. This was introduced in Firefox 3.6, so instead of the iconURL tag, you could just place a file named icon.png in the root of your package and it would work.

Now, on Firefox 4, the Add-ons Manager has an entirely new face. Since the UI resides in a tab instead of a small window, some elements like the add-on icon can now be larger.

The new manager interface has 2 icon sizes: 48 x 48 px for the list view and 64 x 64 px for the detail view. The detail view is what you see if you double-click any add-on on the list (at the moment the detail view scales the icon down to 48px, bug 615980). So, now we also have an icon64URL tag in install.rdf and an icon64.png file we can use for the 64px version of the icon. The default version should be 48px.

There is no perfect way to support both Firefox 4 and earlier versions. I recommend that you switch to the 48px and 64px icons, which means that on earlier versions of Firefox the 48px icon will be scaled down to 32px. Not ideal, but also not terrible. Another possibility is to use both the default icon files and the chrome URLs. If both are present, the chrome URLs take precedence (when possible), and they are flexible enough to point to different files on different versions of Firefox.

Toolbar buttons

Toolbar buttons in Firefox have always been tricky because there are different icon sets for different platforms (with different dimensions), and you need to consider different icon states, like disabled and hover. This XUL School article explains what’s involved in creating toolbar icons for 3.6 and previous versions. Much of this has changed in Firefox 4, increasing the difficulty, while at the same time making a few things much simpler.

What has improved? In Firefox 4 you no longer need to worry about icon states. The CSS in the browser will handle that for you (you can override the CSS if you want, of course). Also, you no longer need to draw the whole button on Mac OS. In Firefox 4 all you need for all platforms is the contents of the button in a transparent PNG. The CSS will add the necessary button styles as long as you set the right class to the element (class=”toolbarbutton-1 chromeclass-toolbar-additional”). This makes the icon sets for Firefox 4 much simpler that their predecessors.

What is more complicated? Now there are more places where you can place toolbar buttons using the customization options. First, the usual places: the main navigation toolbar, custom toolbars and the menubar (except on Mac). Now there are 2 new places: the Add-on Bar (successor of the statusbar) and the tabbar. This means more testing, but as you’ll see, no extra icons or convoluted CSS.

Here are the icons I created for each platform, and what I discovered while testing.

Windows

• The icon is 18 x 18 px. However, there’s plenty of padding inside, so the content is only 15px, like the other icons in the navigation toolbar.
• If you use these dimensions, you don’t need a different icon for the “small icons” mode in the toolbar. All you need is the following CSS that I lifted from the Firefox 4 theme:

#icondemo-toolbar-button > .toolbarbutton-icon {
  margin: 0px !important;
  width: auto !important;
  height: auto !important;
}

This CSS tells Firefox not to scale down your icon in “small icons” mode, only cutting down the surrounding padding. It will behave just like all the other icons in the toolbar.

• The “small icon” mode is also used for the Add-on Bar, the tabbar and the menubar.

Here’s how the icon looks on beta 7:

• Toolbar.

• Toolbar, disabled.

• Toolbar, small icon mode.

• Menubar.

• Tabbar.

• Add-on Bar (the button styling will be removed on bug 598920).

All with a single image. The only default look I’m not too crazy about is in the menubar. I could use CSS to remove the button background and that would probably make it better. Other than that, I think the default styles work fine.

Mac OS X

• The icon is 20 x 20 px. Just like the Windows icon, the contents are restricted to a 15px frame that is centered in the image.
• The color is a dark grey just to keep consistency with the Mac theme.
• There’s no need for any tricks to support the “small icons” mode. On Mac, the only icon that changes size in this mode is the Back button.
• One difference on this platform is that the background color of the tabbar is different if you have the Tabs on Top option on or off. With Tabs on Top, the color is a light gray, otherwise it is a darker tone. If you use a dark color for the icon like I did, there’s no problem, but make sure you test this case.

Linux

• This is the only platform where we really need both icons, since the size difference is considerable. The large icon is 24 x 24 px, while the small one is 16 x 16 px. The small icon has the same contents as the one I used on Windows. For the large one, the contents are 20 x 20 px.
• The CSS code for the small icon goes like this:

toolbar[iconsize="small"] #icondemo-toolbar-button {
  list-style-image: url("chrome://icondemo-os/skin/toolbar-small.png");
}

• Just like on Windows, the big icon is used in the default navigation toolbar, and the small one is used for all other cases.

SVG as an alternative

The SVG implementation in Firefox has progressed a great deal with time, both in completeness and efficiency. It is now possible to use an SVG graphic where an image file would normally go:

#icondemo-toolbar-button {
  list-style-image: url("chrome://icondemo-os/skin/toolbar.svg");
}

This is the reason I chose an SVG image as the base for my demo. It’s much easier to convert SVG to images than the other way around. I did a quick test changing the CSS rule as shown above, and everything worked fine. There wasn’t any noticeable performance hit, which is to be expected for a trivial add-on with a single image. However, since most add-ons just include one button, it seems that choosing SVG is not a bad idea from a performance perspective.

The key advantage of SVG is being able to create a single graphic for all platforms and circumstances. Using CSS you can change colors, sizes and even shapes depending on how the icon is being used. This can also decrease the size of your installer package dramatically if your add-on is heavy on graphics.

The main drawback is to actually create the SVG image. While some design packages can export to SVG, the result can be similar to what you get from WYSIWYG HTML editors. It will require some work to create a good graphic that isn’t computationally intensive to render, and more so if the person in charge of graphic design is not familiar with this technology.

Backward Compatibility

Like I’ve said before, manifest flags are your friend. You can have completely different icon sets and CSS rules for different versions of Firefox on different platforms.

That’s all. I hope this was clear and informative. Feedback and questions welcome as always.