Using the standard theme

by 1 contributor:

By default, no style is associated with XUL extension windows or dialogs. You can either provide a complete custom styling, but most of the time you also want to be able to reuse the standard theme (also called the "Global Skin") of the base application for non-custom elements, transparently with regard to which theme the user has currently chosen.

At the beginning, there is no style

When creating a new XUL <tt>window</tt> (or a new <tt>dialog</tt>, for that matter) in your extension, and you do not associate a style sheet with it, your widgets will be unstyled. Meaning, some internal default will be applied, which does by no means correspond to the standard theme (the theme currently chosen by the user in the Theme Selector), or even the default theme delivered with your the base application.

Applying the standard theme

In order to use the theme currently chosen by the user of the base application (the so called "Global Skin"), you have to add the following line to your XUL file:

<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>

This imports the styles found in the <tt>global/skin</tt> chrome directory and will make the standard XUL widgets of your application use the selected chosen theme. You do not have to specify a specific file; Mozilla will determine by its own which files in the directory it needs to use.

If you are only going to use these global style sheets, you of course do not need a <tt>skin</tt> directory in your extension package, and also do not have to register a style in the <tt>chrome.manifest</tt>.

Adding custom styles

In order to provide custom styling for some of your widgets (apart from the standard global skin) you can take two different routes. You can either add multiple <tt>xml-stylesheet</tt> processing instructions to your XUL file, or create an <tt>@import</tt> chain.

No matter which approach you choose, do not forget to register your custom skin in the <tt>chrome.manifest</tt>.

Note that you can also mix these two approaches, although it makes your code more readable when sticking to only one way.

Multiple <tt>xml-stylesheet</tt> processing instructions

Simply add one <tt>xml-stylesheet</tt> processing instruction for every style sheet you want to associate with your XUL file:

<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>
<?xml-stylesheet href="chrome://myextension/skin/custom.css" type="text/css"?>

<tt>@import</tt> chains

First, import the global skin in your custom style sheet using the CSS <tt>@import</tt> rule:

@import url("chrome://global/skin/");

You then have to associate your XUL file with your custom style sheet only:

<?xml-stylesheet href="chrome://myextension/skin/custom.css" type="text/css"?>

Applying different custom style sheets depending on the selected theme

Mozilla is able to automatically pick your custom style sheet depending on the theme currently chosen by the user. That is, depending on the theme currently selected by the user, you can provide different custom style sheets for your extensions.

For this to work, you need to create an approriate directory structure, with directory names corresponding to the names of the themes you want to extend, and of course, your adapted custom style sheets.

For more information on how to do this, read about theming a custom toolbar button.

Note that both approaches described above work with this automatic style selection.

Document Tags and Contributors

Contributors to this page: Andreas Wuest
Last updated by: Andreas Wuest,