jQuery Tools / Tooltip - Tooltips done right

 

The Story

Tooltips are one of the most important JavaScript widgets on the web. Although important, they also happen to be a very badly misunderstood and poorly implemented component. This tool corrects the situation. You'll get a professional piece of sofware that is easy to understand and use. Here are the highlights of this tool:

• Typically, you will need a single JavaScript one-liner to get started.
• Appearance and dimensions can be tweaked with CSS.
• The tooltip can contain any HTML such as images, tables and forms or it will generate tooltips from each element's title attribute as in the demo above.
• You have full control over the positioning.
• There is an improved event management system for controlling when the tooltip will be shown or hidden.
• You can move the cursor on top of the tooltip so you can use links or form inside it
• You can control the tooltip timings before and after your mouse moves over the trigger element.
• Pluggable effects. Tooltip comes with two build-in effects: toggle, and fade and one separate effect: slide and you can easily build your own effects.
• A dynamic plugin will dynamically change the tooltip's position so that it always stays in the viewport.

This tool uses a simple and natural syntax and has an advanced programming API. You can extend it with callback methods or with your own plugins. This tool has a similar structure and feel as the other tools. Learn to use this tool and you will know how to use the rest.

This tool is a mature project and is actively maintained. The source code is clean, professional and easy to follow. It passes Douglas Crockford's JavaScript Verifier and it it doesn't assign any global variables. Active forums keep this tool alive and you can expect to see new releases coming out in the future.

The available tooltip functionality and configuration variables are minimal because tooltip functionality is inherently simple. If you want to do complex things, you can do them with "normal" jQuery programming. You often see bloated tooltip solutions because they contain functionality that should not be there. For example, if for some weird reason you want to use AJAX requests with tooltips, you can do them with jQuery. AJAX functionality should not be mixed in with the tooltip code.

Usage

We believe that the best way to learn is through demos. The following demos are fully documented and a standalone page is provided to get tooltip working on your site. It's really important to study the first demo "Basics of using the tooltip", because it teaches you the basics of using the library.

• Basics of using the tooltip
• Using any HTML inside the tooltip
• Imitating browsers default tooltip
• Using tooltips in form fields
• Using tooltips in tables or lists
• Custom tooltip effect
• Dynamic positioning of the tooltip

tooltip Graphics

You can use our graphics as the basis for your design. You can freely change the design as you see fit. Click the image on the right to download a zip file. Before using the graphics, you should consult the User's Guide on how graphics can be used when designing the look and feel of the tools.

Here are a few examples of what is included in the zip file:

Configuration

There are many other ways of using this tool than the demos provided above. The generic form of initializing tooltips is the following:

// selectors
$("<trigger_selector>").tooltip({
	/* tooltip configuration goes here */

	// one configuration property
	position: "bottom left",

	// another property
	opacity: 0.7,

	// ... the rest of the configuration properties
});

You select one or more elements with a jQuery selector that will trigger the tooltip(s). The tool looks for the element that is placed next to the tooltip to be the tooltip. The return value is a jQuery object associated with the selection. Here is a full list of available configuration options:

events: {
	def: 	 "mouseover,mouseout",
	input: 	"focus,blur",
	widget:	"focus mouseover,blur mouseout",
	tooltip:		"mouseover,mouseout"
}

Tooltip positioning

The tooltip position is specified with two different configuration properties: position and offset. Both are JavaScript arrays with two values. The position property specifies the position in relation to the trigger element. For example, a value of 'bottom center' will place the tooltip on the bottom edge of the trigger, centered horizontally. The following image illustrates the "slots" that you can use:

The offset property fine tunes the tooltip position specified with the position property. For example, the value [10, -20] moves the tooltip position 10px downwards and 20px to the left. The first value modifies the vertical positioning from the top edge of the tooltip and the second value modifies the horizontal positioning from the left edge of the tooltip. Positive values move the tooltip downward and to the right, while negative values move the tooltip upward and to the left.

Using callback functions

Inside any callback function, the this variable is a pointer to the tooltip scripting API. Here is an example of an onShow callback function that fades out the trigger element when the tooltip is shown:

$("label").tooltip({

	// change trigger opacity slowly to 0.8
	onShow: function() {
		this.getTrigger().fadeTo("slow", 0.8);
	}

});

See the Using Callback Functions section of the User's Guide for a more detailed dscription about this important topic.

Event management

jQuery Tooltip allows you to fully control when the tooltip will be shown or hidden. You can specify different events for different types of elements. You can control this behaviour with the events configuration variable which has following values by default.

events: {
	def: 	 "mouseover,mouseout",				// default show/hide events for an element
	input: 	"focus,blur",						// for all input elements
	widget:	"focus mouseover,blur mouseout",	// select, checkbox, radio, button
	tooltip:		"mouseover,mouseout"			// the tooltip element
}

This specifies opening and closing events for various types of trigger elements. def accepts a value mouseover,mouseout which means that by default the tooltip is shown when the mouse moves over the trigger and hides when the mouse moves away from the trigger. For input elements (text, textarea, password) the tooltip shows when the input is focused and hides when focus moves out of the field.

widget is a convenience type which means select, checkbox, radio and button elements. For them the tooltip is shown on both focus and mouseover events and hidden on both blur and mouseout events. This is just a convenience because these elements usually need same kind of tooltip behaviour.

since 1.1.2 you can also customize the events for the tooltip element. By default the tooltip stays visible when the mouse is moved over it and it is hidden upon mouseout. If you don't want to close the tooltip upon mouseout, you can simply specify: tooltip: "mouseover". This gives you the possibility of closing the tooltip programmatically. This has been done on the login/signup boxes on the main navigation bar of this website.

If you want to customize these events you can follow the example below:

$("label").tooltip({
	events: {
		input: 'click, blur',
		checkbox: 'mouseover click, mouseout',
		date: 'click, blur'
	}
});

This will override the events for every input element. We have also defined customized events for checkbox field. The tool checks for the trigger element's type attribute to lookup appropriate events from the configuration.

The format of the value is: showEvent11 showEvent2 ... showEventN,closeEvent1 closeEvent2 ... closeEventN. You first supply all showing events separated with spaces followed by a comma (,) followed by all close events separated with spaces. A list of available events can be found here. Look for the "Event Helpers" section.

Nothing stops you from adding special types for your elements just by defining a type attribute. Here we use a date type that was added to the HTML5 specification and the corresponding element on the page is defined like this:

<input type="date" name="birthDate" />

Here is a demo that shows you the various event types in action.

Scripting API

This tool has a useful API for scripters. A lot of effort has been put into it so that you can enrich the tooltip experience. You can get a handle to the API in numerous ways as described in the User's Manual. Here is an example of how to access the API:

/*
	get handle to the third tooltip on the page
	(must have been constructed before the call)
*/
var api = $("a.withTooltip").tooltip(2)

// show the tooltip
api.show();

Here is a list of all API methods:

Built-in effect: fade

The built-in effect "fade" has its own set of configuration options as follows:

Making custom effects

If you want to make custom effects, you'll use the $.tools.tooltip.addEffect method. This method is "static", meaning that you don't have to have the tooltip API (or instance) already loaded. You can add effects before any tooltips are constructed.

This method accepts three arguments. The first argument is the effect name, the second argument is the function that performs the required functionality for showing the tooltip and the third argument is a function that hides the tooltip. You can use this method to modify existing effects or add new ones. Here is an example:

// adds an effect called "myEffect" to tooltip
$.tools.tooltip.addEffect("myEffect",

	// show function
	function(done) {

		// 'this' variable is a reference to the tooltip API
		var conf = this.getConf(), tip = this.getTip();

		// peform your effect. for example:
		tip.css({opacity: 1, width: '+=50'});

		// after you have finished you must do
		done.call();
	},

	// hide function
	function(done) {

		// peform your effect. for example:
		this.getTip().animate({opacity: 0, width: '-=50'}, done);
	}
);

As you can see inside the functions the this variable is a pointer to the scripting API. Which gives you access to various parts of the tooltip elements. The functions are fed with one argument which is a reference to a function that must be called after you have performed your effect. The reason for this is that many times those effects perform animations that have a certain duration. We must know when these animations are finished so that the onShow and onHide events are really called after the tooltip is completely shown or hidden.

Note that if you are using jQuery's animate method the "done" function can simply be given to this method as the last argument. jQuery will take care of it after the animation finishes.

The default effect

Effects are actually quite easy to implement. Here are the functions for the default show/hide effect:

// show function
function(done) {
	this.getTip().show();
	done.call();
},

// hide function
function(done) {
	this.getTip().hide();
	done.call();
}

Look at tooltip's source code for more examples of the effects. The basic idea is to use your jQuery skills together with the API methods. Here you can see a demo about the custom sliding effect.

Effects and Plugins

Effect: Slide

The slide effect makes your tooltips slide. Move your mouse over the download button below and you can see it in action:

File	flowplayer-3.1.5.zip
Date	2009-10-24
Size	112 kB
OS	all

New features in 3.1

Here you can see the JavaScript setup for above setup:

$(document).ready(function() {
		
	// enable tooltip for "download" element. use the "slide" effect
	$("#download_now").tooltip({ effect: 'slide'}); 
});

Configuration options

Here is a full list of available configuration options for this effect. These options are added to the default configuration options.

This effect uses a fading animation from zero to full opacity in all browsers other than Internet Explorer.

Example

An example setup using slide effect with a custom property slideOffset:

$("a.withTooltip").tooltip({
	effect: 'slide',
	slideOffset: 30
});

Plugin: Dynamic

Below you can see triggers whose tooltip is centered on the top edge of the trigger. Click here to scroll a little lower and see how the tooltips behave now. We are using the dynamic plugin which repositions our tooltips so that they are always visible in the viewport.

If there is no room on the top edge then the tooltip is shown on the bottom edge. The same happens on every edge of the tooltip: top, bottom, left and right. The opposite edge is always used.

Highlights

• Can be used with any effect
• You can use a custom CSS class name for any repositioned edge. This allows you to style the tooltip differently for each edge.
• You can change the effect and any other configuration variable dynamically whenever repositioning occurs.
• The tooltip's offset configuration variable is inverted. Higher means lower and further right means further left.
• Small file size: only about 2kb of minified code. uncomparable

Usage

The best way to learn is to study the full documentation for the example above. For the impatient here is the JavaScript setup:

$(document).ready(function() {

	// initialize tooltip
	$("#dyna img[title]").tooltip({
	
		// use single tooltip element for all tips
		tip: '#dynatip', 
		
		// tweak the position
		offset: [10, 2],
		
		// use "slide" effect
		effect: 'slide'
		
	// add dynamic plugin 
	}).dynamic( {
	
		// customized configuration on bottom edge
		bottom: {
		
			// slide downwards
			direction: 'down',
			
			// bounce back when closed
			bounce: true
		}
	});
	
});

Configuration

Here is a full list of available configuration options for this plugin.

Note: Currently this plugin cannot be used when the lazy configuration variable is enabled for the tooltip.

Release Notes

  follow jQuery Tools on