• Flowplayer
• jQuery Tools
• Login
• Logout

Tooltip basics

standalone demo

Simple or Rich

A simple call such as $("img[title]").tooltip(); will enable tooltips by taking advantage of the element's title attribute. If you want complex tooltips with images, tables, forms and links that's possible by placing the tooltip element manually next to the trigger element.

Configure design, timing and positioning

Use CSS to create rounded borders, arrows, gradients or shadows. Big or small, high or low. Use the configuration to tweak pre and post-delays and positioning to your personal needs.

Fading, sliding, dynamic

Tooltip comes with two built-in effects: toggle, and fade and one separate effect, slide, and you can easily build your own effects. The dynamic plugin will dynamically change the tooltip's position so that it always stays in the viewport.

File size: 1.10 Kb

This tool has all the features and configuration options you'll possibly need, such as effect and a plugin framework, scripting API and an event model. A smaller codebase is easier to control and results in snappier behaviour. Without gzipping the size is 3.5 Kb.

Usage

Here is the simplest possible Tooltip initialization:

  $("[title]").tooltip();

You select one or more elements with a jQuery selector that will trigger the tooltip(s). The trigger's title attribute will be used as the tooltip content. The actual tooltip element is auto-generated when it is being shown for the first time. Look at the minimal setup to understand the basics.

Manual tooltips

Manual tooltips are HTML elements (typically DIVs) that are placed next to the trigger element and they can contain any HTML such as images, links and tables. The initialization is identical but now we assume that the trigger element does not have a title attribute.

  $(".trigger").tooltip();

After this the element next to the trigger is being used as the tooltip.

Tooltip configuration

Tooltip has many configuration options to tweak the behaviour. Here is an example configuration with two options:

  $(".trigger").tooltip({ position: "bottom left", opacity: 0.7});

Demos

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.

${demo.title}

tooltips 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

        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. 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.

Events

Make sure you have read about Events in jQuery Tools. All event listeners receive the Event Object as the first argument.

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);
  }
 
  });

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:     "mouseenter,mouseleave",    // default show/hide events for an element
  input:   "focus,blur",               // for all input elements
  widget:  "focus mouseenter,blur mouseleave",  // select, checkbox, radio, button
  tooltip: "mouseenter,mouseleave"     // 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 appears when the input is focused and hides when focus moves out of the field.

widget is a catchall 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 some kind of tooltip behaviour.

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 mouseleave. If you don't want to close the tooltip upon mouseleave, you can simply specify: tooltip: "mouseenter". 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 the checkbox field. The tool checks for the trigger element's type attribute to lookup the 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 at the "Event Helpers" section for more information.

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

First make sure you have familiarized yourself with jQuery Tools scripting.

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 the 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: 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.

• report a bug »
• 
• What's new in v1.2.6 »