An overlay is used when it is desirable for a block of content to be shared between several different windows. In addition, it can be used to append or alter content in an existing window. An overlay is defined in a separate XUL file. Overlays are applied while the XUL is being loaded.

Each element within the overlay is inserted at a location in the master window, determined by matching id attributes. For instance, if an element in an overlay has an id of 'filemenu', the corresponding element with the id 'filemenu' in the master window that uses the overlay would be altered. Attributes declared in the overlay are added to that element and child elements are inserted into the window within that element. Elements directly inside the overlay element as children that do not have id attributes are appended to the master window. This allows the addition of scripts to the master window from the overlay.

Overlays do not have an onload event. To have initialization code in an overlay, place it directly in a script outside of a function. This is commonly used to call the addEventListener method to listen to the load event for the window which does not fire until the master window and all overlays are applied.

Overlays may be applied to windows in other packages. Files, such as scripts, that are referenced from the overlay should be specified as absolute URLs. If you do specify a relative URL, it will be relative to the window that the overlay applies to, not the overlay's file.

More information about overlay


class id



Type: string

The style class of the overlay. Multiple classes may be specified by separating them with spaces.


Type: element id, must be unique in the window

A unique identifier so that you can identify the overlay with. You can use this as a parameter to getElementById and other DOM functions and to reference the element in style sheets.

Add a note User Contributed Notes
August 31, 2004, 5:42 am lee dot jonas at uk dot fid-intl dot com
See also insertbefore and insertafter common attributes that can be added to elements inside the overlay to fine-tune their insertion point in the master XUL file. Also, you can remove elements from the master XUL file with (removeelement).
August 1, 2004, 3:11 am poilkj at freemail dot hu
according to my experiences: you can't access elements in overlays by document.getElementById(id), until the whole document has been loaded.

<?xul-overlay href="overlay.xul"?>
<box id="boxoverlay"/>

<overlay id="tooverlay">
<box id="boxoverlay">
<button id="btn" oncommand="alert(document.getElementById('btn'))"/>
// click -> [obejct XULElement]
alert(document.getElementById("boxoverlay")); // [object XULElement]
alert(document.getElementById("btn")); // null

Attach a load event listener to the window using addEventListener to do initialization in an overlay - Neil
January 28, 2004, 2:45 am dvdplm at yahoo dot com
Yesterday I noticed that putting a <broadcasterset> in an overlay does NOT work. They have to be in the main xul file (maybe overlaying the broadcasterset itself might work; havn't tried that).
January 19, 2004, 7:45 am dvdplm at yahoo dot com
Please note that the id attribute on the overlay element is a must, otherwise nothing will show up (the id can be set to just anything: for the overlay id-matching to work the id on the <overlay> does not matter).

Copyright © 1999 - 2005 XULPlanet.com