How to add tooltips to your Joomla! website

From Joomla! Documentation

Revision as of 20:27, 9 February 2009 by Dextercowley (Talk | contribs)

Replacement filing cabinet.png
This Namespace has been archived - Please Do Not Edit or Create Pages in this namespace. Pages contain information for a Joomla! version which is no longer supported. It exists only as a historical reference, will not be improved and its content may be incomplete.
Documentation all together tranparent small.png
Under Construction

This article or section is in the process of an expansion or major restructuring. You are welcome to assist in its construction by editing it as well. If this article or section has not been edited in several days, please remove this template.
This article was last edited by Dextercowley (talk| contribs) 7 years ago. (Purge)

Tooltips Overview

A tooltips is a piece of text that pops up when you hover the mouse over a region on a website. If you use the Joomla! back end, for example, tooltips are used to help explain the action of different parameters, as shown in the screenshot below:

Screen tooltip example 20090208.png

Tooltips are a great way to give the user access to information without using up space on the screen. You can use basic tooltips just by adding a "title" attribute to a tag. However, this doesn't give you the option to style the tooltips. With Joomla! version 1.5, it is very easy to add styled tooltips to your site. This tutorial will show you how.

Note: If you are converting old code, make sure it doesn't use the prototype.js file. That file will keep the tooltips from working.

Activate Tooltip Behavior

To start, you must activate the tooltip behavior. This is done with the following line of code:


Note that you only put this line in once per file. A good place is right after the defined('_JEXEC') or die('Restricted access'); line. If you are curious about what this line does, it inserts the following JavaScript code in the heading of the HTML page:

<script type="text/javascript">
    window.addEvent('domready', function(){ 
       var JTooltips = new Tips($$('.hasTip'), 
       { maxTitleChars: 50, fixed: false}); 

This allows tooltips to function, as outlined below.

Create a Tooltip with the JHTML::tooltip Method

One way to create a tooltip is using the JHTML::tooltip method. The API documentation is available at The method definition is shown below.

void tooltip (string $tooltip, [string $title = ''], [string $image = 'tooltip.png'], 
              [string $text = ''], [string $href = ''], [boolean $link = 1])

The brackets mean the parameter is optional. The first parameter, "$tooltip", is the only required parameter. The equals specifies the default if you do not pass that parameter. For example, the image file 'tooltip.png' is the default image.

The following is a basic tooltip. Keep in mind that the image variable must be in reference to 'includes/js/ThemeOffice'. Use the prefix '../../../' to reference from the root of the Joomla installation.

JHTML::tooltip('This is the tooltip text', 'Tooltip title', 'tooltip.png', '', 

The above will make a tooltip using the default "tooltip.png" image, as shown below.

Tooltip tutorial example screenshot 20090208.png

Clicking the image will take you to, since that is the "$href" argument.

This code is almost the same as above except the image will not be a link (because the "$href" argument is omitted).

JHTML::tooltip('This is the tooltip text', 'Tooltip title', 
               'tooltip.png', '', '', false);

A tooltip can be attached to an image or to text. For example, this code

echo JHTML::tooltip('This is a tooltip attached to text', 'Text Tooltip Title', 
	            '', 'Hover on this text to see the tooltip');

will show a tooltip attached to text, as shown below.

Tooltip tutorial example screenshot2 20090208.png

Note that specifying the "$text" parameter will override any image you have passed to tooltip.

Create a Tooltip Using a CSS Class Name

If we look at the HTML page source generated by the JHTML::tooltip function above, here is what we see:

<span class="editlinktip hasTip" title="Text Tooltip Title::This is a tooltip attached to text" 
      style="text-decoration: none; color: #333;">Hover on this text to see the tooltip</span>

This function generates an HTML "span" tag with the classes "editlinktip" and "hasTip" and an attribute called "title". Notice that the the "title" attribute has two parts, <tooltip title>::<tooltip text> (for example, "Tooltip Title::This is the tooltip text"). You can create a tooltip with only text or with only a title. The title has implications for styling, as we'll see below.

The Javascript inserted by the JHTML::('behavior_tooltip') command we entered earlier picks up this tag based on the class called "hasTip". So, a second way of creating a tooltip is to simply create a tag with a class called "hasTip" and an attribute of "title". For example, this code

<span class="hasTip" title="Text Tooltip Title::This is a tooltip attached to text">
   Hover on this text to see the tooltip</span>

will produce exactly the same effect as the JHTML::tootip() example above.

Adding CSS Styling to the Tooltip

The default tooltips, whether using the JHTML::tooltip method or class method, use the following three CSS classes: .tool-tip, .tool-title, and .tool-text.

Here are the default styles.

/* Tooltips */
.tool-tip {
   float: left;
   background: #ffc;
   border: 1px solid #D4D5AA;
   padding: 5px;
   max-width: 200px;
.tool-title {
   padding: 0;
   margin: 0;
   font-size: 100%;
   font-weight: bold;
   margin-top: -15px;
   padding-top: 15px;
   padding-bottom: 5px;
   background: url(../images/selector-arrow.png) no-repeat;
.tool-text {
   font-size: 100%;
   margin: 0;

If you have a custom CSS file, copy this code and alter it to your liking. Note that the .tool-title class uses by default the "selector-arrow.png" image. This is what gives the outline of the tooltip the little pointer in the upper left of the tooltip box. If you leave out a title in your tooltip, you will just get a rectangle, without the pointer.

Customizing Your Yooltips

Ok, now it's time to have some fun. The JHTML::_('behavior.tooltip') can take two optional parameters. The first parameter is the name of the CSS class that will be used to identify the tooltip. As we saw earlier, this defaults to "hasTip". The second optional parameter is an array of parameters that you can use to fine-tune the tooltip functionality. These are explained below.

  • maxTitleChars: The maximum length of the title (the part of the "title" attribute before the "::")
  • showDelay, hideDelay: The time to delay showing or hiding the tooltip, in milliseconds. Default is 100.
  • className: The first part of the class name used to style the actual tooltip. The default, as we saw, is "tool", and the full class names by default are "tool-tip", "tool-title', and "tool-text". So, for example, if we set this to "custom", we would style the classes "custom-tip", "custom-title", and "custom-text".
  • fixed: Whether or not to have the tooltip move with the mouse. If set to "true", the tooltip will be centered below the text or image. If set to "false", the tooltip will move with the mouse. Default is "false".
  • onShow, onHide: Functions to call for the onShow and onHide events. We'll see an example below where we can use these to create a fade-in and fade-out for the tooltip.

In the next section, we'll show how to use these parameters with some examples.

Tooltip With Different Classes

In this example, we will create a tooltip using different selector and tooltip styling classes. Why might we want to do this? One reason would be if we had different types of tooltips and we wanted to style them differently.

Here is the code to create the tooltip Javascript function:

$toolTipArray2 = array('className'=>'custom2');
JHTML::_('behavior.tooltip', '.hasTip2', $toolTipArray);

In this code, we are creating an array with just one element -- to set the "className" parameter to "custom2". This means that, to style these tooltips, we would use the classes "custom2-tip", "custom2-title", and "custom2-text". Then we call the method with the arguments ".hasTip2" and the array "$toolTipArray". It can be a little confusing, because we have two CSS classes at work here. The class ".hasTip2" is used to identify the HTML tag to create this tooltip for. The class "custom2" is used as the first part of the three CSS classes to use to style the actual tooltip itself.

To use this new tooltip, we could use the following code:

<span class="hasTip2" 
	title="My Tooltip Title :: Tooltip text for hasTip2 class with custom2 style classes.">
	hasTip2 and custom2 example</span>

We are going to make our own tip definitions that include a very cool fade in and out. First create a JavaScript file or simply put this code directly into your code. Pick a name for the class to use. I used "zoomTip".

window.addEvent('domready', function(){
   //do your tips stuff in here...
   var zoomTip = new Tips($$('.zoomTip'), {
      className: 'custom', //this is the prefix for the CSS class
         this.fx = new Fx.Style(this.toolTip, 'opacity', {duration: 500, wait: false}).set(0);
      onShow: function(toolTip) {
      onHide: function(toolTip) {

I'm only going to cover one line of that code here. Please look over the mootools library for more information. I read in their forum that their slider library is not compatible with the tooltips. The 4th line is the prefix for the CSS classes that will be used. In this example the classes will be the following: .custom-tip, .custom-title, and .custom-text.

Here is some example CSS straight from the mootools demo.

.custom-tip {
   color: #000;
   width: 130px;
   z-index: 13000;
.custom-title {
   font-weight: bold;
   font-size: 11px;
   margin: 0;
   color: #3E4F14;
   padding: 8px 8px 4px;
   background: #C3DF7D;
   border-bottom: 1px solid #B5CF74;
.custom-text {
   font-size: 11px;
   padding: 4px 8px 8px;
   background: #CFDFA7;

Notice that .custom-title does not have a background property. This tool tip will be a box without the neat little arrow pointing at the mouse. If you wanted to change the colors in the box and use the arrows you would have to alter the image to have the color you want and add that property into your .custom-title CSS. Now you must create the items using the class method and not using JHTML::tooltip. JHTML::tooltip applies the classes "editlinktip" and "hasTip". I have not seen any way to easily alter that. The code below will create a tip using this new js code.

<span class="zoomTip" title="My Tooltip Title :: Here is my tip's text"></span>

Notice the only difference from the previous example using a span is the class name.

More Information