jQuery: image tooltip tutorial

In this tutorial I will show you a simple but effective implementation of a jQuery image tooltip. All we need is CSS and jQuery, nothing more. As usual, I'll follow a step-by-step approach to help you understand what's going on behind the scenes. Let's get started.

Step 1: The markup

We'll use an unordered list to wrap our images and a global container for the image gallery. In this case, the global container would not be required, but it can actually add a further level of styling if we decide to add more CSS rules to our gallery:

<div id="gallery">

  <li><img src="slide-1.jpg" alt="" /></li>
  <!--other 4 images--> 


The images in the unordered list will be thumbnails, so we need to take this into account when styling our gallery.

Step 2: CSS styles

Our thumbnails will be 100 x 90 pixels wide. Also, we need a right margin on each thumbnail to create an horizontal spacing between images. We decide to add a 5 pixels right margin on each list item, so our gallery will be globally 525 x 90 pixels wide (100 pixels each thumbnail plus 5 pixels each right margin).

Our tooltip will be 500 x 400 pixels wide with a background image on it. This element will host an enlarged version of each image which will be 380 x 240 pixels wide and will be centered horizontally and vertically within the tooltip by using horizontal automatic margins and the top padding:

#gallery {
 width: 525px;
 height: 90px;
 margin: 0 auto;

#gallery ul {
 width: 100%;
 height: 100%;
 margin: 0;
 padding: 0;
 list-style: none;

#gallery li {
 float: left;
 width: 100px;
 margin-right: 5px;
 height: 100%;
 position: relative;

#gallery li img {
 display: block;
 width: 100%;
 height: 100%;
 cursor: pointer;

div.img-tip {

    width: 500px;
    height: 400px;
    background: url(img-tip.png) no-repeat;
    position: absolute;
    top: 100px;
    left: 0;
    margin-left: -200px;


#gallery li div.img-tip img {
 display: block;
 width: 380px;
 height: 240px;
 margin: 0 auto;
 padding: 100px 0 0 0;

We've used floating to align our items. On each item, we've set position: relative so that each tooltip will be positioned relatively to the item it belongs to. In the last rule, we've increased the specificity of our selectors to make sure that the styles specified for the thumbnail images will be overridden on our tooltips.

Step 3: Creating and inserting the tooltips

With jQuery, we need to add the following DOM structure on each list item:

<div class="img-tip">
 <img />

We have to copy the src attribute of each thumbnail to create the tooltip version of our images:

$(function() {

  var tooltip = '<div class="img-tip"></div>';

  $('li', '#gallery').each(function() {
    var $li = $(this);
    var src = $li.find('img').attr('src');
    $(tooltip).html('<img src="' + src + '"/>').
  // continues

After inserting our tooltip, we hide it.

Step 4: Adding the hover effect

When you hover a thumbnail with the mouse, the tooltip must appear by fading it. When you move away your mouse pointer, the tooltip must fade out. Since these two effects will take place on the hover() jQuery event, we have to make sure that only one effect will run each time. For that reason, we use the stop() method with both its parameters set to true. This means: "Execute the current effect but do not create an effect queue". Here's the code:

$('li', '#gallery').each(function() {
    var $li = $(this);
    var $img = $li.find('img');
    $img.hover(function() {
      stop(true, true).
    }, function() {
      stop(true, true).

Adapting the code to your site

The above code works well if your gallery is placed within the main content of your site, say, your main column. However, the choice of using big tooltips might not fit well your needs if you decide to move your gallery to a side column or if the content area is not wide enough to host a 500 pixels wide tooltip. In this case, you have simply to change the size of the tooltip (and its background image) together with the dimensions of the gallery and its thumbnails. To do this, you have simply to recalculate the overall width of each item and the gallery itself.

So if your column or content area is 400 pixels wide, you can make only four images appear on each row (or even three) depending on how many images you want to display. If you want to have four thumbnails with a horizontal spacing of 5 pixels between each image, then your thumbnails must be 95 pixels wide so that you'll have (95 x 4) + (5 x 4) = 400.

Obviously your tooltip dimensions must change accordingly.


Live demo

This entry was posted in by Gabriele Romanato. Bookmark the permalink.

Leave a Reply

Note: Only a member of this blog may post a comment.