Building a Thunderbird extension 5: XUL

Warning: This content is for older versions of Thunderbird. Much of it may no longer be relevant. See for newer information.

Thunderbird's user interface is written in XUL and JavaScript. XUL is an XML grammar that provides user interface widgets like buttons, menus, toolbars, trees etc. We add widgets by inserting new XUL DOM elements into the application window and modify them using scripts and attaching event handlers. While XUL provides the elements of the user interface, actions are written in JavaScript.

For our first extension, we will add some text to the Thunderbird status bar. The status bar is implemented in a XUL file called messenger.xul, which can be found in the chrome/messenger/content/messenger  folder which is packaged inside the omni.ja archive. To view this XUL file use the DOM Inspector extension (no longer supported) or look inside the omni.ja archive, which is located in the Thunderbird program folder. omni.ja can be easily browsed by copying the file to a different location and renaming it to If you have trouble with one zip manager (like 7zip) try another (like WinRAR). In messenger.xul we find the status bar, which looks something like this.:

<statusbar id="status-bar" ...>
 ... <statusbarpanel>s ...

<statusbar id="status-bar"> is a "merge point" for a XUL overlay. XUL Overlays are a way of attaching other UI widgets to a XUL document at run time. A XUL Overlay is a .xul file that specifies XUL fragments to insert at specific merge points within a "master" document. These fragments can specify widgets to be inserted, removed or modified.

In this example you are adding a line to the indented statusbar. Therefore it becomes an item owned by the id called "status-bar". This shows how the Thunderbird architecture allows extensions to modify the user experience without modifying the installation files. This also enables version independence between Thunderbird and Thunderbird extensions.

Example XUL Overlay Document

Create a new file called myhelloworld.xul within the content folder you created earlier with the following content:

<?xml version="1.0"?>
<overlay id="sample" 
 <script type="application/javascript" src="chrome://myfirstext/content/overlay.js"/><!-- A reference to your JavaScript file -->
 <statusbar id="status-bar">
  <statusbarpanel id="my-panel" label="Date"/>

The <statusbar> widget named status-bar specifies the merge point within the application window that we want to attach to. When parsing our overlay file, the XUL engine will take all child elements of the <statusbar> tag and merge them with the original XUL document's <statusbar> tag. In the example above we have defined a new <statusbarpanel> item (that can be referred to as my-panel) which will create a new instance of this widget type and add it at the end of the statusbar. In Thunderbird it will appear as a label at the right side of Thunderbird's statusbar and display "Date".  We have also added a <script> tag that contains a reference to the JavaScript file overlay.js. In the next section you will learn how to use JavaScript to modify your label so that it shows the current date.

The overlay.js file will be created in a later section and your add-on will still work if the file is missing. For now you can ignore this line, but remember that this is how you reference a JavaScript file.