Simple tooltip powered by jQuery

tagged JavaScript by Jon

A great user interface acts as a teacher. It should bring new users up to an intermediate level of experience quickly. Anyone can appreciate a video game that lets them dive in and play without ever needing to pick up the manual. Many games offer help text that appears at key moments to teach the player how the game works.

The web has a lot to learn from video game interfaces. Adding tooltips is an effective way to quickly bring users up to speed so that they never feel the need to find the help manual.

Here is an example of one.

What is a Tooltip?

A tooltip is help text that appears when you hover your cursor over something. The title attribute of a hyperlink or alt attribute of an image tag will be displayed as a tooltip by a browser when you hover your cursor over them.

For example, hover over -> this

These are useful attributes. They should be added to every image and hyperlink. At least for the sake of adding some meaningful metadata.

Why Simple?

Tooltips should be simple and focused on their purpose. Adding extra functionality like a close button or draggability is not necessary. When you hover over a tooltip indicator it should quickly appear, display its message, then quickly disappear when you move your cursor away.

Most people would agree that the ad bubbles that pop up when you accidentally hover over certain keywords are incredibly annoying. This is because they take a while to load, are completely overloaded with information and require you to find the close button to get rid of the damn thing. Good example of bad UI design.

Step 1: The Graphics

First, you will want to chop up the graphics that will be needed. Actually, graphics aren’t completely necessary but I wanted to make things interesting.

Tooltip Graphics

The above is a diagram of how I made and chopped up a speech bubble looking container for my tooltip. It consists of a the top and bottom portion as well as a thin slice of gradient that will be repeated horizontally in the background of the middle portion. I named them “bubbleTop.gif”, “bubbleMid.gif” and “bubbleBtm.gif”.

Slice these out and save them as a gif or png to retain the transparency. Put them in an images folder.

You will want to use an icon as an indicator so that people can identify the tooltips. I used one from famfamfam’s silk icon set. I totally recommend having these icons on hand while developing your websites. They are very well done and, even better, distributed through a Creative Commons Attribution License.

Step 2: The HTML

The HTML required on the front end for this tooltip is extremely simple. Simply add an span tag (however, almost any inline HTML element will work) with a descriptive title attribute. Then, add the class ‘toolTip’. This will act as a hook for the jQuery code we are about to write.

  2. <span title="This is the tooltip text"> </span>

The span tag should look something like this.

  2. <div class="toolTipWrapper">
  3.         <div class="toolTipTop"></div>
  4.         <div class="toolTipMid">
  6.         </div>
  7.         <div class="toolTipBtm"></div>
  8. </div>

The tooltip will be structured like this.

There are four div containers, each with an individual class. The first is a wrapper that holds everything together. Then the top, middle and bottom sections of the tooltip. This will all be dynamically inserted into the element with the toolTip class by jQuery

Step 4: The CSS

Here is all the CSS that is needed.

  2. .toolTip {
  3.         padding-right: 20px;
  4.         background: url(images/help.gif) no-repeat right;
  5.         color: #3366FF;
  6.         cursor: help;
  7.         position: relative;
  8. }
  9. .toolTipWrapper {
  10.         width: 175px;
  11.         position: absolute;
  12.         top: 20px;
  13.         display: none;
  14.         color: #FFF;
  15.         font-weight: bold;
  16.         font-size: 9pt;
  17. }
  18. .toolTipTop {
  19.         width: 175px;
  20.         height: 30px;
  21.         background: url(images/bubbleTop.gif) no-repeat;
  22. }
  23. .toolTipMid {
  24.         padding: 8px 15px;
  25.         background: #A1D40A url(images/bubbleMid.gif) repeat-x top;
  26. }
  27. .toolTipBtm {
  28.         height: 13px;
  29.         background: url(images/bubbleBtm.gif) no-repeat;
  30. }

Now, I’ll go through and explain all of this…

In the toolTip class, the help icon is placed in the background and positioned to the right. Right padding is added to assure that the icon is always visible.

I set the cursor to ‘help’ because it acts as a good visual cue and defines the tooltip as help text.

The tooltip will be generated inside of the HTML element with this class. It needs to be positioned relative so that it will contain the absolutely positioned toolTipWrapper class.

The toolTipWrapper class needs a width to hold the pieces inside together. It needs an absolute position so that it will hover on top of the page content. It’s left coordinates will be dynamically set with jQuery.

Display none is needed in order for the fade-in and fade-out effects to work.

A font size is set so that it stays consistent regardless of what HTML element it is placed in.

The rest of the classes are used to build the tooltip itself.

Step 5: The jQuery

This is the jQuery script that makes the magic happen:

  2. $(document).ready(function() {
  3.   $(‘.toolTip’).hover(
  4.     function() {
  5.     this.tip = this.title;
  6.     $(this).append(
  7.      ‘<div class="toolTipWrapper">’
  8.         +‘<div class="toolTipTop"></div>’
  9.         +‘<div class="toolTipMid">’
  10.           +this.tip
  11.         +‘</div>’
  12.         +‘<div class="toolTipBtm"></div>’
  13.       +‘</div>’
  14.     );
  15.     this.title = "";
  16.     this.width = $(this).width();
  17.     $(this).find(‘.toolTipWrapper’).css({left:this.width-22})
  18.     $(‘.toolTipWrapper’).fadeIn(300);
  19.   },
  20.     function() {
  21.       $(‘.toolTipWrapper’).fadeOut(100);
  22.       $(this).children().remove();
  23.         this.title = this.tip;
  24.       }
  25.   );
  26. });

If you are not already familiar with jQuery, I would strongly encourage you to take the time to learn it.

  2. $(‘.toolTip’).hover(

The script uses jQuery’s hover() function. There are two individual functions inside of it that make up the mouse-over and mouse-out.

  2. this.tip = this.title;

In the first half of the hover() function, the script grabs the content inside of the title attribute and makes a variable out of it.

  2. $(this).append(

It then uses append() to insert the HTML that makes up the tooltip and places the title contents into it.

  2. this.title = "";

The title is set to an empty string so that the browser default tooltip doesn’t appear as well.

  2. this.width = $(this).width();
  3. $(this).find(‘.toolTipWrapper’).css({left:this.width-22})

Then, the width of the element with the toolTip class is taken and the toolTipWrapper is given left coordinates so that it is always positioned directly beneath the help icon.

  2. $(‘.toolTipWrapper’).fadeIn(300);

The function fadein() is used to gradually bring in the tooltip. It also acts as a safeguard to keep it from popping up if someone accidentally hovers over it.

  2. function() {
  3.         $(‘.toolTipWrapper’).fadeOut(100);
  4.         $(this).children().remove();
  5.         this.title = this.tip;
  6. }

The second half of the hover() function resets everything and puts things back to normal. The fadeout() function is used to hide it.


This script was originally inspired by a project I worked on recently that required a little something to help people understand the application.

The tooltip in this tutorial is a simplified version of what I built for that project. I wanted to keep it very simple and leave room for you to experiment with and add additional features.

But remember, too many features is a bad thing. Keep it simple and add only the features that are needed to fulfill your website’s needs.

Get the source files here.

Leave your mark...

If you liked this article please leave a comment and share it.

Add a comment Digg Stumble Upon Reddit

December 2nd, 2007

Hey jon.

Great tutorial – the fact that it runs on jQuery makes it sweeter! Here is a good example of what jQuery can do, I believe you have seen it already.

By the way, Did you enable the cool tooltip here ? When I hover, I see the default style.

And yesss ! The Typography looks Great . I am sure the other users would find it easier to go around the site now.

Yet to see the gravatars, need to push the button for it 😉

December 2nd, 2007


Great site overall! Got you added to the RSS. Looks great will keep checking back!

Ps. You may want to add an RSS link somewhere to make adding you easier.

January 25th, 2008


thank’s for your simply but very good tooltip, I’ve made a simple change (dropshadow and minor fix) but I’ve a problem with zindex.

If I assign tooltip to a layer, the tooltipwrapper show it under the layer bottom.

I’ve try to assign zindex to css but always bottom.

Do you have solution?


January 25th, 2008

@ komax

I would love to take a look at your code and see if I can come up with a solution. You comment doesn’t provide enough information. Send me an email with your code attached and I’ll look into it.


February 5th, 2008

I’m sorry but my source have many image and a lot of css, before sent to you I would like to try to solve here.

Your script create a layer wrapper in absolute position, and inside some layer in relative position.

If the .toolTip link is JUST in parent relative div ie6 and ie7 wrong zindex and put tooltip under following layer.

Example :

<a href=”xx.htm” class=”toolTip” …

The parent DIV of the href is relative and the tooltip insert new wrapper in this absolute position and not in global absolute position, so for FF is the some thigs but for ie (6 and 7) is in the tree of html and bottom of the rest of the website.

I hope correct explain the problem, I think that the solution is position tooltip from “mouse position” and not from hover position but I do not how or change all my layer not in absolute position.

By and regards.


February 5th, 2008

the code example is broken I try with no html tag :

DIV CONTAINER (relative) — inside –> DIV HEADER (absolute) — inside —> HREF TOOLTP.


February 6th, 2008

@ komax

The script I wrote does have issues if it is, for example, placed inside of a container with overflow set to hidden or if it needs a higher z-index. Because the tooltip popup is placed inside the anchor tag. The solution is to place the tooltip div at the very top of the HTML and have it positioned relative to the mouse position like you mentioned.

If I find some time, I’ll rewrite my tooltip to do just that to avoid any z-indexing or overflow hidden issues.

Thanks for bringing this up.

Jason Grant
March 18th, 2008

Well done! This is a proper tooltip. I definitely like this one the best out of all the other ones I have researched. Also using it for one of the apps I am building at the moment. Well done and keep up the good work.


April 30th, 2008

Thanks for this great script!
It is exactly what I was looking for.
The fadeIn effects works fine but the fadeOut doesn’t work for me. The tooltip just hides… Tested with Safari and Firefox on Mac OSX.
Is there a workaround or something?

July 9th, 2008

This might sound really lame but when i click this “Get the source files here.” I go to the example page. I see no download link there.

zen lucas
July 30th, 2008

Thank for this post – its great.

I had an issue with a tooltips appearing below the previous tooltip. Adding the following before the .append resoved it:

zmax = zmax+1;
$( this ).css( ‘zIndex’, zmax );

It bumps the z-index up by 1 each time you hover

September 20th, 2008

I’ve actually been having a hard time finding a jQuery Tooltip that works. This is perfect thank you!

November 25th, 2008

This is great, i was hoping to find something like days for 2 days and now i found it. Thx!

November 26th, 2008

Jon i’m having a problem with the tooltip, the tooltip show up but for some unknow issue it doesn’t display the title, do you have any idea why this might be happening?

Thanks Martin

November 26th, 2008

Sorry again, also have the same problem if the has another class that changes the background image on over

November 26th, 2008


You can feel free to send me an email Jon at my domain.

This article was meant to show a very basic concept of a tooltip as inspiration. Some jQuery/JavaScript knowledge is necessary for this. It’s not exactly a drag and drop script.

Good news though. I’m working on revamping this tooltip and making it into an actual jQuery plugin and resolving a lot of issues that people have been mentioning here in the comments.

Magdo Santana
January 28th, 2009


March 14th, 2009

Thank you very much!

March 18th, 2009

What an elegant solution. Thank you! Equally valuable is the first sentence of this article: “A great user interface acts as a teacher.” That should be required reading for anyone doing web design. Thanks again!

April 2nd, 2009

To those out there who are curious, it works all across the boards on Mac OSX browsers. However, I did find it choking on Opera 9 on Vista.

April 9th, 2009

@zen lucas

WOW! You nailed the IE6/IE7 problem right there. Thank you. Only thing is that zmax HAS to be defined before the script is called. But that’s obvious, isn’t it?

April 24th, 2009

is there a way for it to work if it is within a scrollable div (overflow:scroll)?

September 10th, 2009

Hi! I was surfing and found your blog post… nice! I love your blog. :) Cheers! Sandra. R.

Dina Sakr
January 19th, 2010

Hi Jon,
Thats a great script, Thanks.
i am just having a small problem, im having this tooltip inside a jcarousel thats having overflow hidden to work properly.. but it results that it cuts the tooltip…do you have any work arounds to solve this issue?

Blogger Template Place
January 22nd, 2010

nice tutor dude. thanks

February 3rd, 2010

Hi Jon
Thank you for an imformative tooltip tutorial.
I am just statring out with CSS and JQuery but cannot for my life seem to position the tooltip above the activating object.
Hope you or one of your readers can help me out.

March 18th, 2010


will change to


April 19th, 2010

many thanks easy and simple

Steven Gauerke
May 1st, 2010

I have multiple span tags with class of toolTip. If I hover over the first one…everything is good. When I hover over the second one….all the popups show. I go back to the first one and all show again. Why?

May 5th, 2010

One of the easiest tooltips I’ve seen to implement.
One problem is the fadeout actually doesn’t work since you have remove the tooltip after the fadeOut time. I guess it does it right away.
I see room for improvement where it cuts off if used at the footer since it’s positioned below the text or on the same line, is for the tooltip to be positioned higher (based on some algorithm) so it won’t be hidden/cut off if used else where on the page.
Other than that, great script!

????? ????
June 14th, 2010

great,thanks for tutorial .

June 15th, 2010

Hi Jon,
Great tutorial. thanks!
I’m having trouble displaying tooltips for images: it disappears after the first hover. here’s a sample code I’ve been playing with (I need it to be inside a list):

What is this?>
and what is this ?

Do you know why it wipes out the image?

June 15th, 2010

Oops, looks like the HTML code was deleted, here it is:

li class=”toolTip” title=”This is another tooltip. :)” img src=”img.jpg” width=”100″ height=”100″ What is this? /li

chetan varshney
June 18th, 2010

Thank you so much. its realy exelnt. but my dear frnd its not working in Google Chrome browser cud u plz help me??

July 11th, 2010

As first, thanks to your effort to JQuery Example!

JQuery is amazing technology for customizing excellent user interface. I wish you can create others more.

November 30th, 2010

This is simple and easy tool tip, Can you folks help me getting with div holding image and content when mouse over on the div container.


Add a comment

This comment system uses Gravatars for customized avatars. Get your account here.

If this is your first comment, it will be held for moderation. I'll get to it as fast as I can. Thanks :p