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.


Toolbar button - 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.

Icon in toolbar, Windows

  • Toolbar, disabled.

Icon in toolbar, disabled, Windows

  • Toolbar, small icon mode.

Icon in toolbar, small icons, Windows

  • Menubar.

Icon in menubar, Windows

  • Tabbar.

Icon in tabbar, Windows

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

Icon in Add-on bar, Windows

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

Toolbar button - 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.


Toolbar button - LinuxToolbar button, small - 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.

37 comments on “Toolbar buttons and icons in Firefox 4”

  1. Joe wrote on

    My apologies if this is a bit off topic, but finding decent icons are always a big headache for many developers. If we had something like Babelzilla for enhancing the GUI of extensions that would be great! Anyway, does anybody know where can I hire a professional designer at good rate?

  2. Pepe wrote on

    When will the new add-on screen look like the mockups?

    Beta 8 is about to be released and it is not even close. Wrong border color, no gradient background.

    1. Justin Scott (fligtar) wrote on

      Beta 8 has most of the new Add-on Manager Styling in it. You can see it in the current nightly builds.

  3. Nils Maier wrote on

    Well written, I think.

    Some nits:
    * The *nix sizes aren’t actually fixed, but just implied; i.e. there is not actually any CSS that explicitly defines these sizes.
    The result is, that if your toolbar only contains stock icons and the actual default toolbar might be smaller (e.g. with certain KDE/Qt themes)
    This has a direct implication for using SVG on *nix: viewbox’ed svg icons will not render.
    You need to add some platform specific CSS rules for that.

    * Another nit about SVG: When specifying absolute height and width (Inkscape default), as opposed to a viewbox, the svg image will not be scaled, and might even be cropped.

    * You cannot create sprites when using SVG.

    To me, right now it seems to make more sense to just ship plain raster images instead of SVG, because of the aforementioned problems.

  4. ancestor wrote on

    Why is the padding around the icon part of the image, instead of being added by CSS? If it was done with CSS:

    1. We could use the same image for Mac and Windows, as the actual icon size is the same. This makes for one less image, one less platform-specific CSS file, and one less line in chrome.manifest to deal with.

    2. We wouldn’t need the extra rules for small icons mode.

    1. Jorge wrote on

      You can do that, surely. I emulated what was being done in the Firefox code because it’s the easiest way to get it right. But you’re right, it’s probably worth it having the extra CSS in order to save space with extra images.

      1. ancestor wrote on

        Actually, I was suggesting that Firefox could do it in its own theme code. This way, extensions wouldn’t have to worry about padding at all AND they wouldn’t have to worry about the distinction between Mac and Windows. It would save about half of the work. Unfortunately, it seems unlikely to be changed this late in the cycle – and even less likely post-Firefox 4 because we wouldn’t want to break extension yet again. Still, worth filing a bug?

        1. Jorge wrote on

          I think it’s a little late for that. I’m pretty sure it will get very low priority, considering that the workarounds are not bad.
          However, I’m not one to discourage good things, so if you feel strongly about it, go ahead and file it. You can copy me on it (:jorgev) and I’ll make sure it gets some attention.

  5. Brian wrote on

    For cleaning up SVG exported by tools such as Inkscape have a look at scour by Jeff Schiller:

    It does a pretty good job and can also be used to address the viewbox issue Nils Maier mentioned, i.e. if you specify “–enable-viewboxing” it will add a viewBox attribute and set width and height to 100%.

    I believe it’s also available as an Inkscape extension.

  6. Ken Saunders wrote on

    Jamey Boje is a professional graphics designer who’s been with the Mozilla project for a long time and has created a lot of graphics for Mozilla (some official ones) including for He is also the creator of the Firebug logo, administrator for,, and
    He’s also a great guy.
    @jameyboje on

  7. Michael Kaply wrote on

    Part of the problem through this whole process is that everyone is focusing on what to do for Firefox 4.

    Most of us live in the real world where we build addons that support Firefox 4, 3.6, 3.5 and sometimes even 3.0.

    An example that showed creating icons that work on older platforms as well would be much more helpful.

    Please consider in future examples, not just showing what changed for Firefox 4, but how to create solutions that work in older browsers as well.

    1. Christopher Finke wrote on

      For extensions that need to support versions before 4.0, I’ve taken the following strategy:

      For toolbar button images in CSS, I reference two images:skin/ toolbar-big.png and skin/toolbar-small.png. Those two files are the same icons I always used for Firefox 3/3.5/3.6. I also have more icon files specifically for FF 4 on Mac and Windows (toolbar-mac.png, toolbar-win.png). In chrome.manifest, I add override rules to point toolbar-big and small to toolbar-mac.png when it’s FF4 + Mac, toolbar-win.png when it’s FF4 + Win, and to just use the small and big.png files when it’s Linux (any version) or a Mac/Win version prior to 4.0.

    2. Jorge wrote on

      I think most developers will know how to adapt what they have to what is included in this article, if that’s even possible. Christopher Finke already gave you a possible solution, but I worked under the assumption that scaling was not a option and new icons needed to be created. If scaling is not a problem, then I don’t think it’s all that hard to adapt your current set and it would make this post unnecessarily long.

  8. Mook wrote on

    Please don’t ever use !important, especially in CSS in content/ – they can’t be overridden from skins.

    In general, this all ignores the possibility of non-default skins…

    1. Jorge wrote on

      I agree with that policy in general. Like I said, I was mimicking what is being done in the Firefox theme, which includes the !important. They may be necessary, but I haven’t tested that.

  9. Wladimir Palant wrote on

    Sorry to say it like this but that design is an incredible mess and whoever thought it up apparently didn’t spend a minute thinking about add-ons. So in most cases we essentially have 16×16 icons but we still need three (!) different images? And if we want to use 16×16 images everywhere we have to mess with the theme which will wreak havoc when a non-default theme is used? Yes, I understand that Firefox developers don’t have this problem – they already ship different themes for all platforms and custom themes will cover default Firefox UI anyway. But for add-on authors this makes things very complicated and fragile and unnecessarily so. I agree with ancestor above – this really had to be fixed in the Firefox theme. I would have filed that bug long ago but I simply didn’t know that somebody had the great idea to make the sizes different for all platforms. I was assuming that all of them used 18×18 images (which is already bad enough).

    For extensions that need to support older Firefox versions as well as other applications, it seems that the best approach now is to keep 16×16 and 24×24 images. For Firefox 3.x we still have two scenarios (big icons, small icons). The small icons scenario is the same in Firefox 4, big icons are also unchanged on Linux. But for big icons on Windows and OS X we now have two special Firefox 4 cases: use small images and add 1px padding on Windows, 2px on OS X and pray that it won’t break with custom themes. Also prey that other applications won’t follow suit because things will very quickly become unmanageable (I am currently supporting six different applications).

    Sorry, I strongly disagree with the statement that these workarounds are not bad.

  10. ancestor wrote on

    I filed bug 616472:

  11. Michael Kaply wrote on

    This is just another example of Firefox developers showing complete disregard for addon developers.

    If the theme designers had taken five minutes to investigate the problem, they would have figured out that just using 16×16 icons and adjusting the padding for different platforms would have made things work correct on all platforms.

    15×15 icon content? really? It’s hard enough getting things looking good in 16×16.

    1. Nils Maier wrote on

      Well, the UX team was aware of the issues, but then dropped the ball completely, as you should know…

  12. Kohei Yoshino wrote on

    The Japanese translation of this articles is available at

  13. hl wrote on

    What should I see with the icon demo addon? The icon in all different places? Nothing visible here. Could you please indicate how to use it?

    1. Jorge wrote on

      The icon doesn’t show up by default. You’ll need to open the toolbar customization panel and place the icon where you want to see it.

      1. nico wrote on


        I tried it but no button (excepted the 15 or so default Firefox buttons) appears in the “Customize Toolbar” panel. And I have got the same problem with my addons, using Firefox 4b7 and 4b8.

        What could be wrong? Has something else changed regarding toolbar buttons?

        1. Jorge wrote on

          Can you please send me a message to jorge AT mozilla DOT com? You’re the second person (or maybe the same one) I’ve heard with this problem on Linux.

          1. Chris Finke wrote on

            I’ve been having the same problem on Mac since b7 came out.

          2. hle wrote on

            I think this problem is now solved and fixed somewhere between vers. 4.08 0or 4.09. Thx!

  14. nico wrote on

    It is the first time I am reporting the problem. I had a closer look at it, and it actually comes from “Ubuntu Firefox Modifications” (version 0.9b2) extension… which is not flagged as compatible with the last betas.

    It will however not explain why this issue could be happening on Mac OS.

  15. Flavio wrote on

    I am still failing to get the proper icon style and image in windows and mac if I follow the exact instructions. I actually do not get my icon to show. It shows this:

    For my windows button I am using the following CSS:

    list-style-image: url(“chrome://path-to-my-add-on/skin/win_f4.png”);
    #my-win-f4-button > .toolbarbutton-icon {
    margin: 0px !important;
    width: auto !important;
    height: auto !important;

    Any idea what goes wrong? I would also appreciate if you guys would provide a proper instruction how the CSS styling etc should be done for Firefox 4 Toolbar icons. I haven’t found a neat and clean resource yet. Thank yo in advance.

    1. Jorge wrote on

      It looks like the style is not being applied to your button. Either you haven’t included the CSS file in the right place, there’s a mismatch between the ID in the XUL and the one in the CSS, or the CSS file is not being loaded due to a parsing or encoding error.

  16. Volans wrote on

    Thank you for the explanation of the toolbar icons for all platforms, is very useful, but I have a problem, at least on Linux.

    I have a toolbarbutton of type “menu” and if I set the “class” attribute of the “toolbarbutton” element to “toolbarbutton-1 chromeclass-toolbar-additional” as you suggest, the menu’s arrow is shown below the icon/text of the button and not on the right, as expected.

    Moreover, if I omit the “class” attribute, the menu’s arrow is shown correctly and the icon resize well but if the toolbar is in “text+icon” mode the text is shown near the icon and not below, as expected.

    Have you any suggestion?
    Thank you very much.

  17. Kohei Yoshino wrote on

    A Japanese translation of this article is available at

  18. Matt wrote on

    Firefox 4, by default, sticks toolbar icons in those buttons, so it has a border around it.

    How can we get the icon to display on it’s own, as it does on previous versions? Displaying on it’s own not only looks better, but the icon can be bigger too.

  19. Ken Saunders wrote on

    Try these

    background-color: transparent !important;
    -moz-appearance: none !important;
    border: none !important;
    background-image: none !important;
    box-shadow: none !important;
    min-width: whatever px !important;
    min-height: whatever px !important;

  20. Ken Saunders wrote on


    Does this apply to XP?
    skin > classic > icon.png

    And this to Vista and Win7?
    skin > classic > aero > icon.png

    If not, what’s the difference?

    Also, is it still a fact that the Firefox 4 theme for XP will not change?

    I’m styling a button to match Fx 4’s theme for Vista and 7 and if XP is going to remain unchanged for 4, then I’m going to style a button for it specifically, otherwise it won’t look so good on XP.

    I’d like to learn how to have my buttons adapt to the various themes for Linux too like I saw in the mockups for it.
    Any idea where I can find info on that.

    I understand your point that using a single graphic is the best practice, but it isn’t always practical as noted in the case above for XP.
    I’m going to look into using an SVG, I love that idea, but time is running out for me to get this add-on done.

    1. Jorge wrote on

      I’m not sure what you’re asking in the first part of your comment.
      Regarding the XP theme, I think the current theme should be final. I haven’t heard anything about last-minute changes. So yes, ideally you should use different icons for XP and for the more modern versions of Windows.
      I don’t know of any Linux theme guides, sorry. Some distributions use add-ons to customize the look and feel to match the theme.

  21. Ken Saunders wrote on

    Thanks a lot. I really appreciate your help.

    The first part was just asking if they applied XP and Vista/Win 7 separately and I found that they do.

  22. gerdami wrote on

    Some of my toolbar icons just disapeared today from their toolbar locations but also from the icons set when trying to customize them again.