A tooltip is used to provide descriptive help to the user about the control that the mouse is over. For instance, moving the mouse over top of a toolbar button and waiting for a second can display a small popup label containing text describing the button's function. When the mouse is moved again, the tooltip disappears. This is a useful means of providing additional details about a user interface without cluttering up the main interface.

Note that tooltips can only be activated using the mouse, so they should never contain important information that isn't available elsewhere.

The tooltiptext attribute

In most cases, the tooltip will display only a single label. For this, the tooltiptext attribute may be used, which is valid for all XUL elements. The value of this attribute should be the text to appear in the tooltip.

<toolbarbutton label="Back" tooltiptext="Go back one page"/>

In this example, a Back button on a toolbar is given additional text to appear on a tooltip. This could also be useful if the toolbar is configured such that labels do not appear.

If an element does not have a tooltiptext attribute, yet a parent element does, the parent tooltip will apply. For example, in the following, a toolbar has a tooltip set for it.

<toolbar tooltiptext="File Buttons">
  <toolbarbutton label="Open" tooltiptext="Open a File"/>
  <toolbarbutton label="Close"/>

The 'Open' button has a tooltiptext attribute so will have a tooltip of its own. However, the Close button does not have a tooltip associated with it, yet the parent toolbar does. The result is that the toolbar's tooltip will apply when the mouse is moved over the Close button, as well as when the mouse is over an empty part of the toolbar.

Note that the tooltip text 'File Buttons' isn't a good tooltip to use either. It conveys no additional information to the user, so it shouldn't be used as in this example.

The tooltip element

Tooltips are displayed using a tooltip element, which is a type of popup, but is styled to look different. Elements that use the tooltiptext attribute display the tooltip in a default tooltip element, which typically looks like a small yellow box large enough to fit the text inside it. This default tooltip is created automatically, so you don't normally need to use a tooltip element.

However, it is possible to use another tooltip element that looks differently, or which supports other elements besides a single text label.

The tooltip can be created using the tooltip element, the contents of which appear inside the tooltip.

<tooltip id="iconic">
  <image src="help.png"/>
  <label value="Save a file to a remote site"/>

<button label="Save" tooltip="iconic"/>

In this example, a tooltip with the id 'iconic' contains an image and a label. A button is associated with the tooltip using the tooltip attribute. The value of the tooltip attribute should be set to the id of a tooltip element, in this case, 'iconic'. This will cause the tooltip to appear as the tooltip for the button element.

Thus, there are two ways to set a tooltip for an element, using the tooltiptext attribute for labels and the tooltip attribute for more complex content. If an element uses both attributes, the tooltiptext attribute is used with the default tooltip.

If you don't place any elements inside a tooltip element, it behaves and appears just like a standard tooltip.

Note that when using a specialized tooltip element, any labels used inside it are not populated based on what the tooltip applies to, so you may need to set the content in a tooltip if you wish to use the same tooltip for several elements. This can be accomplished by using a popupshowing event listener and adjusting the tooltip as needed. The popupshowing event will be fired on the tooltip element just before the tooltip appears. For example:

<tooltip id="iconic" onpopupshowing="this.lastChild.value = document.tooltipNode.label;"/>

The document.tooltipNode property of the document holds the element that the mouse is hovering over. In this example, this property is examined to retrieve the label of the element that the mouse is over. This label is then set as the value of the last child of the tooltip. In the earlier example, the last child of the tooltip is a label. The effect is that the value of the label within the tooltip will change based on the element that the mouse is moved over.

Tooltips in Trees

As the entire body of the tree is displayed using a single element, the tooltip and tooltiptext attributes do not apply to individual rows or cells of a tree. However, the tree will automatically display tooltips for a cell when the value is cropped. For instance, if a cell has a long label and the column is shorter than the label's length, a tooltip will appear when the mouse is moved over the cell so that the user can see the entire value.