Toolbar buttons in Firefox 4 – revisited

Update: I initially indicated these changes applied to beta 11, when it reality they apply to beta 12. You can test this on the currently nightlies or wait for beta 12 to try it out. The samples work on beta 11, with only one bug: if the toolbar is in large icons mode, the large icon will be used and scaled down on themes where icons are always small, like on Windows.

A couple of months ago I wrote an overview of toolbar buttons in Firefox 4, including all the CSS and image work necessary for your add-ons to work on all 3 platforms. It was met with many questions, the gist of them being why is this so convoluted when it could be really simple? So, bugs were filed and revisited, and many problems were finally solved.

Firefox 4 beta 12 will contain fixes for bug 626382 and bug 616472, both of which bring the necessary icon and styling work down to almost the bare minimum. You can test these changes on the current nightlies

First of all, if you followed the recommendations in the previous article, no changes should be required. I tested the add-on I created for that post on the latest beta on all platforms and it worked just the same. So, if you already did the compatibility work for Firefox 4 testing in earlier betas, you should be good. Now let’s get to the new, simpler way of doing this.

Assuming you want to support all 3 major platforms and your add-on adds a toolbar button, the minimum you need is a 16×16 px icon and a 24×24 px icon. The 24×24 px icon is normally only used on the default Linux theme (I tested on Ubuntu) on Large Icons mode, which is the default value for the main toolbar. For all other platforms and modes, the 16x16px icon is used, with varying margins around it on Windows. In terms of CSS, all you need is this:

#icondemo-toolbar-button {
 list-style-image: url("chrome://icondemo/skin/toolbar-large.png");

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

Nothing else is needed.

Now, if you want to take this one step further and be a better Mac OS X citizen, your icon will look much better if it’s monochrome. For this, I recommend using chrome manifest flags to either have completely different skins altogether, or just override the main skin with the Mac OS skin when necessary. The sample add-on in the previous article uses the former, the sample add-on in this one uses the latter.

Here’s a link to the demo add-on I adjusted for the new system. It’s simpler and smaller because of one icon and some CSS files that weren’t needed anymore.

If you’re a theme author or you want to understand the details of the new system, perhaps if you need specially-sized icons for your add-on, you should read this comment that explains the changes very well. Alfred Kayser also maintains this Mozillazine thread up to date with everything that concerns theme authors. Thank you, Alfred!

Also, special thanks to Dao and Paolo for all the hard work they put into resolving these bugs!

20 comments on “Toolbar buttons in Firefox 4 – revisited”

  1. Joe wrote on

    I am confused! In windows OS even in latest beta edition of FF, when “Use small icon” is unchecked, then Large icon is used, but the actual icon area is still 16X16. It simply means that the 24X24 icon gets stretched to fit to the area! Is it suppose to work like this?

    1. Jorge wrote on

      I think that’s a bug in my implementation. I’ll review this tomorrow, but I think that changing toolbar[iconsize=”large”] to #navigator-toolbox[iconsize=”large”] in the CSS should fix the problem of the incorrect icon being used.
      Good call.

      1. Markus Stange wrote on

        I think it will have the opposite effect. The iconsize attribute of the toolBOX will always reflect the size chosen in the customization panel; only the toolBARs’ iconsize attributes are updated with the actual used icon size. There’s no bug in your implementation.

        It probably doesn’t work for Joe because he tested with beta 11 which doesn’t contain the fix.

  2. Kohei Yoshino wrote on

    As always, our Japanese translation is available at:

  3. Wladimir Palant wrote on

    In other words – you do it exactly the same way you did it in Firefox 3.x. Nice!

  4. Dao wrote on

    The toolkit default icon size is ‘large’. Which means that you should flip the rules:

    #icondemo-toolbar-button {
    list-style-image: url(“chrome://icondemo/skin/toolbar.png”);

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

  5. Markus Stange wrote on

    Bug 626382 hasn’t made it into Beta 11, as far as I can tell. People should test with a nightly build instead.

  6. Belgarian wrote on

    The FF4 addons don’t even want to install on FF4Beta12pre nightlies ?

    1. Jorge wrote on

      If you are referring to the demos, they have maxVersion = 4.0.*, so they should install correctly. What problem are you experiencing? Is this for all add-ons or just the one linked in this blog?

  7. Brian King wrote on

    What I have observed in Mac is that 16×16 are used across the board in the default theme, including in Customize…

    If I put a 24×24 icon in the regular rule (i.e. without [iconsize=”small”]) it is ignored by the toolbar but not in Customize where it appears larger than the other icons. This sounds like a Firefox bug.

  8. Michael Kaply wrote on

    I just found one more weird thing at least on Mac.

    The customize Toolbar dialog uses the large icons, not the small icons.

  9. Michael Kaply wrote on

    Just read Brian’s note and realized I said the same thing.

    The fix for the customize toolbar problem is to have three rules:

    toolbar[iconsize=”large”] #your-toolbar-button
    list-style-image: url(“LARGE”);

    toolbar[iconsize=”small”] #your-toolbar-button
    list-style-image: url(“SMALL”);

    /* Only used for customize toolbar dialog */
    list-style-image: url(“SMALL BUTTON”);

    Unfortunately the downside to this is that on Firefox 3.6, in the customize toolbar dialog, the icon is too small.

    The “fix” for this is that the customizeToolbar dialog should have explicitly used iconsize=small

  10. BrunoLM wrote on

    And how do I add the toolbar button on addon-bar by default when someone install my addon? The code here ( ) mess up with other buttons, is it a bug?

    1. Jorge wrote on

      Can you be more specific about the problem? There are a number of add-ons that already add their buttons to the Add-on Bar by default, and it appears to work well.

  11. eagleone wrote on

    This is all way too complicated!! Seriously guys, get yourself together. Take the way Google Chrome handles extension icons as a reference and make it even better. The situation right now in Firefox is just unacceptable and for me as an add-on developer it is much more fun to develop for Google Chrome. Bring the fun back (well not really back, finally introduce fun to making Firefox Add-Ons).

  12. Musbar wrote on

    Dear Jorge.
    I took the XPI file a is
    from this link
    and I installed to firefox 4.0.1
    It shows in the list of Add-ons,, however, it does not show in the icos,,, I cannot see it in the show/hide list either 🙁 please help me .. I am a newbie to this

    1. Jorge Villalobos wrote on

      Musbar: after installing and restarting, you should be able to see the button the Customize dialog. Right-click on the toolbar and select Customize. Then you need to scroll down in the selection panel because the button will appear last on the list. I just tested on 4.0.1 on Mac OS and it worked OK.

      If it continues to give you problems, please send me an email (jorge AT mozilla DOT com).

  13. Jon Yang wrote on

    I’m trying to figure out how to make a toolbar button for a Firefox add-on and frankly it’s a complete mess. The demo add-on linked in the article is not compatible with Firefox 6.0.2. Is the method to create the toolbar button still the same or has that changed? Is there a more updated article for Firefox 6 compatibility?

    1. Jorge Villalobos wrote on

      Nothing has changed for toolbar buttons since Firefox 4, and I don’t expect anything to change in the near future. The sample should work correctly with the Add-on Compatibility Reporter installed, but you’re right in that I haven’t updated its compatibility since then.

      I’ll do this soon. Sorry for the inconvenience.

    2. Jorge Villalobos wrote on

      After too many delays, the demo has been updated. Sorry for the wait…