HelpBalloon.js version 2.0

I’ve completed my updating of my aging AJAX help balloons / tool tips / dialog balloons / whatever you want to call them.

New features included:

  • Less library dependence. It’s still prototype.js-based and dependent, but no longer requires Scriptaculous nor the prototype “improvement” script that they previously used. You can optionally still use Scriptaculous if you want the sexy fading effects. Just include the scriptaculous.js file in your document and the balloons will detect it and use it, no configuration needed. (However, if you want to use different Scriptaculous effects than the standard Fade and Appear, you can set the hideEffect and/or fadeEffect options to whatever you want… Doesn’t even have to be Scriptaculous, just Scriptaculous-compatible)
  • Use any object as an anchor point. This was available in later revisions of v1, but I’ve solidified it’s support. Simply assign the anchoring element as the balloon’s icon property at instantiation. (See the example page for details)
  • Anchor postioning control. This feature allows you to move the anchor around within your icon for fine-tuning the balloon’s display. (See the example page for details)
  • Non-caching remote data requests. If you’ve ever tried to use v1 of the balloons with dynamic data, you’d know that once the balloon makes it’s first request, it caches the request result and would not make subsequent calls for fresh data. You can now force the balloon to make a fresh request before each showing using instantiation options. (See the example page for details)
  • Fixed direction assignment. By default, the balloons will position themselves based on available realestate, but you can now assign a fixed direction using instantiation options. (See the example page for details)
  • Still 100% free, now released under the MIT open source license.
  • Better organized and fully commented/documented code. This was a complete refactor/rewrite of the code base, and I made sure to comment the code very thoroughly and try to explain my reasoning (or insanity) as best I could. In addition, I’ve written a proper API page, and have revisited the examples page.

As always, I’m eager to hear feedback — be it wishes, comments, praises or curses. Thanks to all that provided feedback on v1, it was tremendously valuable.

Click here to download the full widget (includes images, HelpBalloon.js, prototype.js, and scriptaculous 1.8.1) 556k zip.

Or you can get the latest via GitHub:

Click here for the API Page

Click here for the Example Page

Update: I’m right in the middle of adding new feature documentation, so the docs are a little wonky. I’ll fix shortly.

This entry was posted in AJAX, Development, Widgets. Bookmark the permalink.

179 Responses to HelpBalloon.js version 2.0

  1. André says:


    Great job on the help ballon!
    One question only…how can I have larger title string on the balloon without getting it hidden?
    Thanks in advance

  2. amanda says:

    another question. Can you interact with the balloon and then have it disappear on mouseout?

  3. Kris Martin says:


    How do I resize the balloon? I tried the ,
    balloonDimensions : [100,50] but no luck.

    PS. Great work…!

  4. jakob says:


    great work btw!, i have another question….
    when creating your own custom balloons is there a way to offset the x & y for actual balloon in relation to the icon, as my anchors are located in the middle


  5. Busybee says:


    thank you very much for this flexible and well-documented tooltip!

    I am trying to change it so to have a much bigger bubble (500px by 500px) right now. I will get back to you with the results / problems ;-)

  6. Busybee says:

    …well, I found out by just replacing the balloon .png with a bigger one, it works out of the box.

    Wow! Thank you so very much for this script.

    The only thing I now need to do is to show an ajax loading indicator for my ajax – balloons.
    What I would like to do is show that indicator overlaid over the anchor of the balloon, once I click it. Then, when the balloon content is ready, it will be hidden. For some of my ajax content, the load is pretty heavy and I need to entertain my users for the 1-2 seconds the pulling of html content takes.

    Any ideas how I can automatically place that loading indicator at the spot I clicked?

  7. Dennis says:

    I want to load the ballon in a dynamic peace of ajax.
    But the innerfunction will not allow load javascript within ajax.

    I Mean, i have a button for MyBla. Clik on it and the page will be loaded dynamical. in this php code i put the ballon. Within the dynamic page i need at least 5 helpballons.But the javascript will not be executed. any ideas?

  8. George says:


    I have uploaded the helpballoon folder on a windows 2003 server but the page doesn’t show the “i” icon so to click on it and show the balloon. Do I have to install any components on my server to run AJAX?

  9. Vijay says:


    great tool. Is there a way i can make the balloon to popup upon an hover on a hyperlink, instead of forcing an icon?
    I tried but could not figure a way to avoid using an icon

  10. Vijay says:

    oh well – i figured it out – a similar feature was right there in an example – thanks for the great tool and even better examples :-)

  11. Suba says:


    This is a wonderful tooltip….Great Work….

    I have a small issue…when i try to resize the balloon by specifying the dimensions it doesnot seem to work….even i tried replacing the ballon with a smaller one….no luck………any idea why thats happening….


  12. Jason says:

    Can you think of any reason why the popup balloons are not shown in Internet Explorer but they are fine in Opera and Firefox? Everything else works fine when you click on the icon (text works, even using .xml as its source, and the format is correct, just missing the balloon image). A pathing issue that IE doesn’t like maybe?

  13. Jason says:

    As a follow-up to my last comment, I discovered that there is an issue with IE using PNG images with alpha channels. Is this what is causing the problem, and if so will you publish new .png images and/or a way to fix the issue? I’m including the URL and the text I’m referring to below. Thanks!

    Note: Internet Explorer

    The balloon body image is in PNG format with alpha channels. This file format is required for the semi-transparent shadow. Older versions of internet explorer do not support this feature (support was added to version 7). In the default configuration, an alternative image without a shadow if substituted is IE version

  14. Beau says:

    I’d be interested to know what version of IE you’re having difficulties with. I’m looking at the example page and it works fine in IE7. Also, the script already uses the PNG alpha-channel workaround so that wouldn’t be the issue. If it was, you’d see a black background behind the balloons.

    Let me know,


  15. Jason says:

    After doing further testing, it does work just fine with the same computer (IE 6.0.2800.1106 for the record) if I use static .html (via apache) and the same scripts. The problem occurs when I use it in a java servlet (via JBoss) using .xsl. Maybe it’s being served but IE interprets it differently than Opera/Firefox. I’ll look into it more and see what I can come up with. Thanks for the quick response.

  16. Beau says:

    Ah, that makes sense.
    XMLHttpRequest objects are sensitive to what the document type is from the server’s response. It dictates whether the responseXML or responseText are populated. Be sure the expected response type is set.
    However, now that I think about it, there might be an issue when trying to read XHTML that is served with an XML doc type. I’ll have to do some testing on this and get back to you.


  17. Jerome says:

    Great tool!

    I have 1 problem though. My balloon image is 650×200. When I run it, the balloon is truncated. The entire 650×200 is not displayed. Is there something I am missing?

  18. Arthur says:


    I’m sort of new to this, and I like the mouseover technique.

    How the heck does one install this? I’ve always been curious, and I copied the mouseover code from the example page, but obviously there is more to it than that……

    Thanks in advance!


  19. Busybee says:


    going back to my first posting, I am struggling to make this happen:

    Whenever I click the anchor of a help balloon (An ajax help balloon), I want to show a small activity indicator on top of the anchor I clicked.

    What I can do is set up an ajax activity indicator that appears whenever there is some ajax activity and dissappears once the content is ready.

    What I can not figure out is

    1) find out how to place the gif at the coordinates of the anchor (preferably the center)
    2) how to make it appear on top of the anchor where ever on the page that is.

    I understand this is not exactly on topic but I think an Ajax help balloon needs this, as it can take a few seconds before the balloon pops up and that delay might be irritating to some users.

    Pls help!

  20. Herve says:

    Everybody has already told it, it’s really a great library.

    Is it possible to use it without a background image ?

  21. Chuck says:

    I have been looking for something like this for a while now, thank you. Can this be used with an image map? If so, how?

  22. Craig says:

    Thanks for creating a great application. Two questions though: I’m using it on mouseover, how do you get it to disappear on mouseout, it kinda just stays there until you click the ‘x’. Also is there a way to delay the balloon popup on mouseover, i have many popups on one page and the user might get annoyed if they are sliding their mouse around and all these balloons popup, if there was a way to do like a one or two second delay that would be cool. I’m using a different icon which is quite large, so this happens a lot during testing.

  23. Greg Martin says:

    Great tool!!

    But I can’t for the life of me figure out how to change the dimensions of the baloons. I see balloonDimensions in the documentation, but I can’t get it to accept anything I try.

    A quick tip on that would be much appreciated.

  24. Dimitris says:

    Can you please help me with the dimensions? Where do i specify them?

    thanks for a GREAT great tool.!!

  25. Jerod says:


    Thanks for writing this, it has helped me a lot. I do have a (difficult?) feature request. Variable height Help Balloons. I realize you’d have to do a lot of reworking to get away from the current fixed size images but it would be well worth it for those awkwardly long (or short) help texts.

    Love what you’ve done so far, keep it up!


  26. Cobus says:

    Hi Beau

    First off, great control, and kudos on the API and documentation.

    The balloon works great except for one issue. I have a custom anchor, and have disabled caching by attaching a guid to the dataURL, as I found that when using cacheRemoteContent the server is hit with many (> 10) request per balloon, which impacted on performance. The issue is, when I close a balloon and then open the same one immediately after, TWO balloons are opened on top of each other, and the user experience is that you have to close the balloon twice before it closes. Any advice?

  27. H says:

    I can’t figure out how to get long titles to display (instead of cutting off). I’ve tried resizing the .png but that did not work. Anyone know what to do?

  28. Tanya Bub says:

    Hi Beau,

    Love the script! I got it up and running with no problems and it looks gorgeous. I’d love a balloonDimensions example so that I can resize the balloons if you have one. Other than that it is a thing of beauty.

    Muchas gracias!

  29. Jason says:

    As a follow up to my issue above with the balloon images not being displayed, I’ve fixed the problem on the client computer running Internet Explorer by applying the ‘Update for microsoft core xml services (msxml)6.0 service pack 1′ via Windows Update. The URL for the update is here:

    I hope this helps, thanks!

  30. alex says:

    Hi there,

    thanks for this great script.
    I have few questions:

    1) I’m using a large image as anchor for multiple balloons, but I want to have one one visible at time. How can I destroy/delist the former balloon at the time I’m creating the new one or in alternative how can I update the coordinates of the existing one?

    2) I read related questions to update the coordinates and content of the baloon, it would be great to see an example added to you tutorial.

    Thanks again


  31. Arun says:

    Great Tool.

    How can I pass dynamic value to the dataURL? Depending on the value entered by the user, I have to populate information in the balloon.

    Please let me know.


  32. Pingback: Huge list of Tooltips | Javascript, CSS, Tons of examples… |

  33. deepanaresh says:

    hi, I am using Ajax baloon in my project. The only issue that i am facing is when i am placing it within the update panel. The icon gets disappered when the update panel updates.
    I have tried all sort of ways ..but could not succeed.

    Please advice me how to deal with this …. Thanks

  34. Craig B says:

    Great looking tooltip. It is just what I have been looking for. My only issue is after I submit the page (using an AJAX update panel) the javascript seems to stop working and the tooltip does not show. Am I missing something? Any help would be great because I would really like to use this great looking control! Thank you.

  35. Kirt says:

    This seems good product except I am new to Dreamweaver CS3. I have downloaded ‘HelpBloon’. Now I have no idea how to install the package!!

    Do I copy the files to the Dreamweaver CS3 folder or what?


  36. Shadow says:

    Has anyone figured out how to change the balloon’s dimensions or get them to close automatically without selecting ‘X’?

  37. Scott says:

    I just ran across you blog this morning. Just want to say thanks for all the interesting information I didn’t even know I needed. Keep up the good work, Scott

  38. Sebastian says:

    As everybody already said: Great Script! Thanks a lot.

    But still I have difficulties concerning the balloonDimensions. Either they don’t work or I am too stupid ;-). Maybe you can add this one to the examples page since more people are wondering about how to use this property.

    Thank you.

  39. Alex says:

    Hi, i’ve just started using your very good baloon library and i’ve some problem regarding the z-index of the baloon. They appear on back of my container! :( There’s a way to change the z-index directly when I create the baloon? I haven’t undestand how to change the style at runtime… Thanks in advance. Very good software :)

  40. andy says:

    how can i change the dimensions of the balloons ?? PLEASE HELP !

  41. Beau says:

    Currently the size of the balloon is dictated by the size of the background image. I know this seems backwards… Then next release will include scaling. (I’m hoping to have this done by the end of the month)


  42. Samdhal says:

    balloon images are not getting displayed…
    on IE7 as well as on FireFox…
    can anyone help or faced the similar issue ?

    In FF it says :
    Warning: Expected end of value for property but found ‘)’. Error in parsing value for property ‘background’. Declaration dropped.

    What’s the problem …. ?

  43. this is great, i you can put images into the tooltips also, great script for those who don’t wish to over clutter their forms etc..

  44. Sreenadh says:

    Great work.

    if I create balloon toolitip inside an iframe, it will not be positioned correctly in firefox.

    I modified the code as below
    /* var ww = Prototype.Browser.IE ? document.body.clientWidth : window.outerWidth;*/

    var ww = Prototype.Browser.IE ? document.body.clientWidth : window.innerWidth;

    Now it works on both IE7 and FF

  45. Scott says:

    How can I pass a dynamic value to the dataURL? Depending on a value entered by the user, I have to populate information in the balloon from an external .jsp and I want to send that external .jsp file the value through the dataURL.

    Is that possible with this tooltip? Any ideas?

  46. Scott says:


    I was wondering if there was a way to delete balloon instances when the user closes out of the balloon? When I click on a tooltip anchor multiple times, all balloon instances are being stacked which causes the user to have to close multiple balloon instances each time.

    Thx in advance

  47. Pingback: Mayron Cimardi Blog » Lista: Links legais (e úteis!) de Ajax/DHTML

  48. Tom says:


    hows the status on changing the size of the balloon?
    please release a new version fast
    since now its worthless if you can’t resize the thing

  49. Arul says:

    Thank you for this great scripts.

    I was wondering if there was a way to show the balloons outside an iframe if the icon is inside the iframe?? Any idea??

  50. Hello!

    Great work but i have a question. With which browsers ist the Helpballoon compatible?
    Is it also compatible with IE 6 ?

    Please answer me!



  51. Arul says:


    Thanks for this great script.

    I was wondering if there was a way to show the balloon outside an iframe if we set the icon inside iframe?? can anyone help??

    Thanks before.

  52. Arul says:

    @Alexander Prinz
    Hi Alex, I just try this script with 3 browser. IE, Firefox and Opera. Everything is Ok. This is realy cool script. Try it! :)

  53. Benniog says:

    Hi Beau,
    Great script, works really well…
    I have discovered a problem in IE 6… if you add a form item i.e. input, select or button it show through in the middle of the balloon.
    This is bound to be a problem with the way that IE handles the DOM, i think I have found a workaround by layering an iframe underneath the balloon… this feels like a bit of a hack so it might be something that you want to look at fixing in another release…

    Great work

  54. Bob says:

    The question I have is how would I call a specific batch of info from an xml file? The idea is to put all the help item content in a single XML file and then read the appropriate piece when you mouse-over the info icon. I don’t want to create a million little xml files.


  55. Bob says:

    Uh oh. Using this in an website and in a Multiview control. Seems to work fine in the first view but as soon as I load the second view, all the icons are gone. Not sure what the problem is.

    And there has to be a way to call data in from a single file for multiple help balloons and point to specific data for the particualar icon/control.

    Resizing of this balloon would be useful. I tried editing the graphic and I changed the height of the balloon but it still displayed using the same size container. Maybe someone can point me to where in the js the container dimensions are figured so I can resize my balloon.


  56. Hennio says:

    Great script! The only thing I cant figure out is a hide on mouseout. Is there an easy way to make this happen?

  57. Ron W says:

    Any idea when the “balloonDimensions” property will be supported?

    Without it, this becomes rather worthless.
    I hate you see you put so much effort into this, Beau, only to not finish it.

  58. Che says:

    Very nice script Beau!
    For some reason, even when I resize the background image in IE6, it doesn’t resize the balloon properly (though it does great in Firefox)
    I know you are working on this and even on scaling in your next release.

    In the meantime, I think I see how you were originally using balloonDimensions, so I tried to re-enable that feature in order to force the dimensions to work in IE6.

    1. line 675 comment out the code that sets the dimensions to the width of the image

    // this.balloonDimensions[0] = this._lastBalloon.width;
    // this.balloonDimensions[1] = this._lastBalloon.height;

    2. line 1147 at the bottom of HelpBalloon.Options add a new parameter:

    balloonDimensions: [0,0]

    3. line 238 set the balloonDimensions when the balloon is initialized:

    this.balloonDimensions[0] = this.options.balloonDimensions[0];
    this.balloonDimensions[1] = this.options.balloonDimensions[1];

    4. that’s it. then just create a new balloon object and pass it balloonDimensions:

    var hb4 = new HelpBalloon({ balloonDimensions: [900,300] });

  59. Nagaharish says:

    pls any one just do one small help. How to use this in u give coding it will be great….!

    Thank to all

  60. Quinn says:

    Hey, great job on the helpballoons – thanks so much for making this available. I know you get what you pay for but can I make one request – keeping in mind I really appreciate your work, but …

    PLEASE – RESIZE – this is really needed or the balloons are only working at about 25% of what they could be. Looks like the tag in the documentation is not working:

    balloonDimensions: [200,300]

    PLEASE release an update – there are FIVE other comments above asking for this… again, you have done great work, got paid nothing, thanks much… just go for this one update and you’ll have something great tons of people will use!

    Thanks again!

  61. madeureka says:

    hi, great work, i wonder if is a posibility to use the onmouseout functions, i want when i mouseover to show and when mouseout to hide.
    please help me, i canot figure the last thing, the mouseover work great

  62. madeureka says:

    <a href=”#” id=”" onclick=”return false;” style=”color: #FFFFFF; font-weight: bold” >Quick Info!

    var hb5 = new HelpBalloon({
    title: ‘Product Information’,
    content: “Product Name:  Product Code:  Production Studio:  Avaible Stock:  (without cart items!)”,

    useEvent: ['mouseover'],
    icon: $(”)

    Event.observe(”, ‘mouseout’, hb5.hide.bind(hb5));

  63. Chris says:

    So… anyone figured out how to resize the balloon’s dimensions? I’m stuck too.

    Is Beau on holidays? :-)

    Any help? Please?

  64. Chris says:

    OK, so I’ve got either a workaround, or maybe how the resize is supposed to work (special thanks to my colleague Caley for figuring it out):

    So, the image width and height (of the speech bubble) is dynamically grabbed and the tooltip is sized accordingly. If you want to create different sizes, make balloon-alt’s of all four images with the size you want. Then, when you’re calling the balloon, add this:

    balloonPrefix: ‘../images/tooltip/balloon-alt-’

    Where the stuff in the quotes is everything before the 0,1,2,3 numbers of the alternate balloons you should have created.

    And so, on that note, while it is dynamic, it just might not be the dynamic you were thinking of – hats off to Mr. Scott for a great little library!

  65. Richard says:

    Great little script but balloonDimensions doesn’t seem to work.

  66. Amit says:

    Hello Beau!

    Thank you for the scripts! I have one question, could you please help me? My page has multiple controlls with the same ID. Is it possible to use this script in this schenario? Right now, what is happening is that – if there are 30 hyperlinks with the same ID in the page, then 30 balloons are diplayed 0ne over another when the first hyperlink is hovered over, for the rest it is a java script error!

    How can I make this script work in this scenario?

    You answer will be heartily appreciated.


  67. Squeez says:

    I have done some modifications to the file “HelpBalloon.js” and created a new bigger balloon-graphic for one position. With this mod I’am able to display the normal sized balloons and one bigger balloon in position “bottom_left”. It should be no problem to add more and different sized balloons in the same way.

    Additionally I’ve added a new option for each balloon to identify the part within the XML file where the content of all balloons is saved. You will need only one XML file to store the contents for all of your balloons! The new option is called “no”. This option is set to a string with any content you want (i.e. ‘balloon1′). In the XML you have to set a part with “” and “” the define the content for this balloon.

    1. First I have added a news position with id 4 and named it “POS_BOTTOM_BIGLEFT” (add this in the position-definition (ca. line 60)):

    * Enumerated value for the bottom-left rendering position.
    * @static

    2. Add the definition for the new option “no” (ca. line 210-220):

    * Number for HelpBalloon (used for identifiying the XML-Part)
    * @var {String}
    no: null,

    3. Modify the preload-function (ca. line 240-260):

    // Preload the balloon and button images so they’re ready
    // at render time
    // 0 1
    // X
    // 2 3
    this.balloons = [];
    for(var i = 0; i < 5; i )
    var balloon = new Element(‘img’, {
    src: this.options.balloonPrefix i this.options.balloonSuffix

    this.balloonDimensions[0] = this.options.balloonDimensions[0];
    this.balloonDimensions[1] = this.options.balloonDimensions[1];

    4. Add the new position within the pos-calculation (ca. line 260-280):

    case 4:
    zx = this.balloonCoords.x – this.balloonDimensions[0];
    zy = this.balloonCoords.y;

    5. Modify the XML funtion (ca. line 660-690):

    // Attempt to get the title from a HTML tag, unless the title option has been set. If so, use that.
    matchTxt = ‘/\([^\<] )\/gi’;
    var htmlTitle = cont.transport.responseText.match(matchTxt);

    matchTxt = ‘/\|\/gi’;
    htmlTitle = htmlTitle.toString().replace(matchTxt, ”);
    this._titleString = htmlTitle;
    this.options.content = cont.transport.responseText;

    6. Change the dimension-vars (ca. line 680-700):

    // this.balloonDimensions[0] = this._lastBalloon.width;
    // this.balloonDimensions[1] = this._lastBalloon.height;
    this.balloonDimensions[0] = this.options.balloonDimensions[0];
    this.balloonDimensions[1] = this.options.balloonDimensions[1];

    7. Create a XML file with all of your balloon-”no”s (example):

    Content for ballon 1

    Content for ballon 2

    8. You always have to add the option “balloonDimensions” and “no” in every balloon creation. The dimensions (i.e. [600,300]) depends on the size of your bigger balloon graphic. The size of the original balloons is [300,240]. (example (balloon1 is my own bigger balloon, ballon2 is an original-sized balloon)):

    $balloon1 = <<<CODE

    new HelpBalloon
    dataURL: ‘help.xml’,
    no: ‘balloon1′,
    balloonDimensions: [600,300],
    fixedPosition: HelpBalloon.POS_BOTTOM_BIGLEFT // 4


    $balloon2 = <<<CODE

    new HelpBalloon
    dataURL: ‘help.xml’,
    no: ‘balloon2′,
    balloonDimensions: [300,240],
    fixedPosition: HelpBalloon.POS_BOTTOM_LEFT // 3



    You have to add new positions and graphics for each balloon you want to display with other sizes. My new balloon in this example is sized “600 x 300″ pixels and named “balloon-4.png”.

    I’m not sure if this is the best solution for resizing the balloons, but I’ve never done something with javascript before, so I think it is ok.

  68. Squeez says:

    Sorry, the comment filters some code-content, so my comment before is not completely displayed.

    I’ve uploaded my modified files here:

  69. Ivan says:

    Hi, has anyone found a solution for the configuration of the z-index. I am using this library together with jCarousel and the images of jCarousel are displayed on top in Firefox 3. However, with IE7 it is fine.

  70. Quinn says:

    Resize? Oh please – I love your help balloons – once they are resizable they will be UBIQUITOUS… please hook us up!

    Got a beta build? Seems everyone is looking for this…

  71. cesar says:


    Great script.

    It doesn’t seem to be compatible with the moo-tools framework though. prototype.js seems to kill mootools. Any idea why?

  72. Pingback: I tooltip in javascript | Flatiron's website

  73. Roman says:

    Beau, very nice script.

    I tried to implement a tooltip myself with scriptaculous just by defining a hidden div and using the effects Appear/Fade. I am using a png image with alpha transparency as a background image for this div. What I noticed is that IE shows a black border during the Appear/Fade effect. I applied the following css to the div:

    _background: none;
    _filter:progid:DXImageTransform.Microsoft.AlphaImageLoader(src=’graphics/tooltip.png’, sizingMethod=’scale’);

    This made the png display right in IE 6, but still I have no luck with getting rid of the black border.

    However, I noticed that your script doesn’t have the problem. What is the fix you used? Do you have to add the alpha transparency filter to the script and not just the css?

  74. Kip says:

    Is there a way to change the body text alignment. Instead of centered I would like to have it left justified. I looked through the API information and found “content” and “content margin” but did not find anything on alignment or justification.


  75. junoreactor says:

    Hi, i’ve just started using your very good baloon library and i’ve some problem regarding the z-index of the baloon. They appear on back of my container! :(
    and an other problem:
    The html select are over the balloons
    There’s a way to change the z-index directly when I create the baloon?

    Thanks in advance.
    Very good job :)

  76. Stefan says:


    nice tool. I am having a problem with IE6 (6.0.2900). Form elements underneath the balloon are not hidden. I tried to set the option “hideUnderElements” but that did not help. Is IE6 supported? Is there a workaround for this problem? It is a nice tool, but this problem is preventing me from using it.


  77. Bossi says:


    first off, thanks heaps this tool is pretty nifty indeed. Love to see ppl developing stuff for the community, good work..

    I don’t know if it’s just me but I don’t seem to be able to change the buttonX and buttonY position for some reason. Anyone else got that problem or is it really just me?

    Cheers & keep up the good work! ~

  78. Pingback: 30+ Tooltips Scripts With Javascript, Ajax & CSS

  79. Pingback: 30个tooltips工具提示演示及下载 - 虾米碗糕|十里地后院

  80. Tadeusz says:


    I try to use multiple events, like that:

    useEvent: ['click','mouseover']

    but this causes no reaction to any event. Any suggestions?

    Thanks for the great component.

  81. Tadeusz says:

    I think I have fixed the problem reported in the last post. Here it goes:

    toggle: function(event)
    if(!event) event = window.event || {type: (this.options.useEvent.length == 0 ? null : this.options.useEvent[0]), target: this.icon};
    var icon = Event.element(event);
    var found;
    for(var i = 0; i < this.options.useEvent.length; i )
    if (this.options.useEvent[i] == event.type)
    found = true;

    if(found && !this.visible && icon == this.icon)

  82. charles says:

    I too have tried to get the balloonDimensions element to work.
    I resized the graphic and set balloonDimensions: [600,500], but the container doesn’t adjust.

    Interestingly, 2.0 requires prototype and scriptaculous both if you want to display tables in the content.

    Otherwise, this is an awesome tool. Hopefully, the Dimensions issue can be resolved, fixing the only serious flaw I’ve had with this tool.

  83. sandeep says:

    HI Beau,
    Great work …
    Actually I need some larger ballons. So please provide me the code and images or link to them, if you have successfully implemented those. Its really a great help.

    Great Work !!!

    Thanks & Regards,
    Sandeep Manocha

  84. paulo says:

    As people keep saying – great work (presumably so that you might be more inclined to answer their questions). My question is, can you trigger the balloons externally when using image maps?

  85. Jason Morris says:

    Hi Beau

    I found this recently and it rocks – looks awesome and is really space-efficient.

    I have found one problem though – it doesn’t seem to work with older versions of Safari :-((

    I have two old laptops with 1.3.2 and 2.0.4 and both show just the text without the background image. Worse still the text is transparent so you lose it against the background :(

    Seems to work okay on my iphone Safari so may just be an “old” problem. I’m going to try and download latest Safari for PC and try that…

  86. Jason Morris says:

    The good news is that it works fine with the latest Safari for PC (v.3.1.2). Haven’t upgraded either of the other two (both Macs) so maybe someone else could confirm it is fine on latest Safari for Mac.


  87. cavanuex says:

    i use Using other events to trigger the balloon and Using a different icon example #1.

    How to make the icon sticky at bottom left of browser?
    just like comodo autenthic site icon, they stick at botom left corner.

    thanks in advance.

  88. Dena Jordan says:

    Fantastic widget Beau!

    I was thinking of using a MySQL table to hold all the help text – would it be possible to read in a specific record for each balloon?

    I guess I could add an option, but I am not all that au fait with javascript.

  89. Pingback: Tooltips Scripts: 50+ Scripts With AJAX, Javascripts, CSS & Tutorials | || Webmaster Accessary Platform

  90. Pingback: Linkit 12.1. - 13.1. | Valontuoja

  91. fedrok says:

    Very nice library!
    But incompatible with jquery.
    I’ve got a collision: if put jquery inclusion before HelpBalloon.js inclusion doesn’t work jquery else viceversa if put jquery inclusion after HelpBalloon.js inclusion doesn’t work HelpBalloon.js.
    Can you help me?


  92. fedrok says:

    Here is the solution for the right dimensioning of the ballon: find in file helpBalloon.js the following lines:

    this.balloonDimensions[0] = this._lastBalloon.width;
    this.balloonDimensions[1] = this._lastBalloon.height;

    Then substitute the code above with the following:

    if (this.options.balloonDimensions != null) {
    this.balloonDimensions[0] = this.options.balloonDimensions[0];
    this.balloonDimensions[1] = this.options.balloonDimensions[1];
    else {
    this.balloonDimensions[0] = this._lastBalloon.width;
    this.balloonDimensions[1] = this._lastBalloon.height;

    Now it works!
    But make attention to non restrict so much the balloon rispect to the content, otherwise there may be javascript errors.

    Good luck! That’s all folks.


  93. Pingback:

  94. francesco says:

    If i put a link in the ‘content’ it works but the document can’t be validated as strict xhtml… any clue?

    the validator says
    document type does not allow element “a” here

  95. Kris says:

    Great tool! You’re an excellent coder. I see you’re working on the balloon dimensions. Is there a way to include a newline in the content? For my particular use on, I’d like the title of the comic book to stand out, and be separated from any other detail I might include about that comic book. It would be cool if I could include the “Add to Cart” button within the balloon too! I suppose if I used a dataURL — haven’t tried that yet.

    Mainly I wanted to say thank you for the free use!!

  96. Kris says:

    oh yea? How to close on mouse out? Or how to close when using another image as the anchor? In IE6, when I click on one of my comic books, I get a lot of js errors as it seems the balloon stays ‘open’.

  97. Maarten says:

    As some people asked about resizing the Balloons:

    The dimensions are taken from balloon-3.png. So if you want to resize the tooltip, you only have to resize the pngs.

  98. Pingback: Tooltips Scripts: 50+ Scripts With AJAX, Javascripts, CSS & Tutorials | BeckMint

  99. Pingback: Tooltips Scripts: Scripts With AJAX, Javascripts, CSS & Tutorials « Online Free Applications Software Tips Tools Wallpapers

  100. Teo says:


    Wonderful work i love it so much but i have a big problem i can not see the balloon icon on ie7. With ff and opera it’s all perfect but on ie7 i have javascripts error and i can not see the “i” icon. The error is on line 1767 in prototype.js. Have somebody an idea? Thank you very much, sorry for my bad english

  101. Anthony says:

    I found a “somewhat” hack to make it so the dimensions are configurable without requiring a custom image for each dimension:
    1. Modify HelpButton.js to add “height” and “width” to the options
    In the “prototype” method add the following (don’t forget to add a comma after the autoHideTimeout option):

    NOTE: I added the parameters into two area of the file (around line 218 after _lastBaloon:null, and around line 1152 after autoHideTimeout:0,)

    2. Modify HelpButton.js to resize the imag
    var balloon = new Element(‘img’, {
    src: this.options.balloonPrefix i this.options.balloonSuffix
    if (this.options.width != null) {
    balloon.width = this.options.width;
    if (this.options.height != null) {
    balloon.height = this.options.height;

    3. You may also need to modify/set the contentMargin parameter to get the margins to work (I haven’t had much time to play with this one, but hopefully this will help some of you) :-D

  102. Paul T. says:


    very nice script!
    I’ve been playing around with it for a few days now, changing background, tweaking styles, using classes etc… to suit my needs

    One thing I found interesting was to take into account page scrolling when choosing the 0, 1 2 or 3 position dynamically. Here’s what I changed:

    Original code:

    var pos = 1;
    if(this.options.fixedPosition == HelpBalloon.POS_DYNAMIC)
    var offsetHeight = this.balloonCoords.y – this.balloonDimensions[1];
    if(offsetHeight < 0)
    pos = 2;

    Modified code:

    var pos = 1;
    if(this.options.fixedPosition == HelpBalloon.POS_DYNAMIC)
    var cso = document.body.cumulativeScrollOffset();
    var offsetHeight = this.balloonCoords.y – this.balloonDimensions[1] – cso[1];
    if(offsetHeight < 0)
    pos = 2;

  103. Mihaid says:

    Hy Scott,

    The balloons look great.

    Only that I have a small js problem.

    The error show to me is:

    Error: too much recursion
    Source File: http://localhost:1000/refman/scripts/ajax/prototype.js
    Line: 263

    i.e. (i’ve just downloaded ) 1.6.1 – RCE

    line 263 is:

    return __method.apply(null, [this].concat($A(arguments)));

    from the block
    methodize: function() {
    if (this._methodized) return this._methodized;
    var __method = this;
    return this._methodized = function() {
    return __method.apply(null, [this].concat($A(arguments)));

    Any ideas ?:-/ Or suggestions ?

    Maybe you are using an older version which…….works just fine :)


  104. josh says:

    I would like to use this from a Microsoft ASP.Net 2.0 AJAX enabled web project.
    Can you give some steps how. Or do you a sample project for ASP.NET?

  105. d1s0rd3r says:

    how can i install this script? thanks

  106. eulerss says:

    i was trying with balloon dimensions but with no much success, is anybody found the right solution?
    thanks in advance!!

  107. Charlie says:

    Is there any examples or documentation on how to have multiple bubbles pop up and disappear when you use the show/hide feature?

  108. Dharshana says:


    Can somebody help me how to resize the ballons. I went through all the posts and nobody has given correct answer yet


  109. Pingback: FREE..! Tooltips Scripts (AJAX, Javascripts, CSS) Plus Tutorial « HendraBozzieBlog!

  110. Manuel says:

    The problem with resizing the balloons is because balloonDimensions is actually never referenced when rendering the image (the _draw() function). It is always referencing the properties of _lastballoon:

    Code (lines 673-674):
    this.balloonDimensions[0] = this._lastBalloon.width;
    this.balloonDimensions[1] = this._lastBalloon.height;

    With the code above, no matter what balloonDimensions contains, it is never read.

    fedrok’s solution doesn’t work because there is no balloonDimensions in options. Based on that, I did the following in the _draw() function:

    /* Commented out these lines */
    // this.balloonDimensions[0] = this._lastBalloon.width;
    // this.balloonDimensions[1] = this._lastBalloon.height;

    /* Added these 2 lines for the Dimensions to be correctly read */
    if (this.balloonDimensions == null) {
    this.balloonDimensions[0] = this._lastBalloon.width;
    this.balloonDimensions[1] = this._lastBalloon.height;

    After that, you just need to define your balloonDimensions where you create the balloon according to the size of the image you want to use. In my case:

    function createBalloon (t, c, i) {
    var b = new HelpBalloon({ returnElement: true, title: t , content: c, icon: $(i), contentMargin: 20, autoHideTimeout: 1000, fixedPosition: HelpBalloon.POS_TOP_LEFT, hideOtherBalloonsOnDisplay: true, anchorPosition: ‘bottom left’ });
    b.balloonDimensions = [294,114];

    return b;

    Hope this helps.

  111. Arvid R says:

    Great script and documentation. I only have one problem. My swedish and german characters å ä ö and ü will not show correctly in the balloon, but everywhere else on the page. Any ideas?


  112. Ben says:

    Got the popup working great but is there ay way of controlling the z-order of the balloon?

  113. joe says:

    I am using motools core and more version, when i include prototype.js i get inject is not a function error. How to solve this problem

    • maca says:

      Have you found a workaround for the problem? I’m also using mootools and I tried to rename ‘inject’ from prototype.js to ‘Inject’ and I’m still getting the error.
      Please help!

  114. Ted Gilchrist says:

    Suppose the cacheRemoteContent: false isn’t working for me. Where is the cache, and how can I dump it?

  115. Ted Gilchrist says:

    Ok, I just answered my own question. First, the cache is stored with your browser, and you can clear it there. Second, suppose you didn’t have cacheing turned off. Then, stuff would get cached. But then you turned off cacheing. Why doesn’t your stuff go away? Because it’s already cached. So clear your cache, and THEN, future changes won’t be cached. This WILL be on the final.

  116. wendy says:

    Does anyone know how to edit the line spacing and make the title longer? Please help!

  117. Pingback: 25 Useful Scripts for Tooltips | Vandelay Design Blog

  118. Pingback: 35 Useful Scripts for Tooltips | JKookServ Hosting Blog

  119. Pingback: 35 Useful Scripts for Tooltips | OnColorz Technology News - New Technology, Internet News, Software, Telecom, Computer Science

  120. Irving says:

    Great tool. Nicely written.

    My problem is that I load HTML on the fly on my page. I make AJAX calls that return the HTML that I insert into a predefined div. In that HTML is the code for the balloon.

    But the Javascript that I download with the HTML does not run.

    Thanks for your hard work.

  121. Pingback: 16款Javascript提示工具(Tooltips) « 幻岛|领地

  122. argonbuy says:

    great work presumably so that you might be more inclined to answer their questions

  123. Ben says:

    Hi Scoot, thanks a lot for this good stuff :)
    very practicle and well done !

    but I have a question, after customising helpBalloon, I need to make it open when the page is loaded !
    I tried a lot with useEvent and the code for event but it didn’t works.
    have you got an idea please to make it ?

    Thanks for your help !

    good luck to continue


  124. Robert says:


    Why can´t I use this script with another scriptlibary like Jquery, at the same time? I using both thickbox and tooltip whit jQuery libary and I like to use Helpballoon at the same time!

  125. It did not worked in Internet Explorer.

  126. does it work in IE 6 as well?

  127. Pingback: 35 Beautiful Tooltips Scripts Using Ajax, JavaScript, CSS | Designer Wall

  128. Pingback: Tooltips Scripts: 50+ Scripts With AJAX, Javascripts, CSS & Tutorials | Beytullah GÜRPINAR

  129. Gunter Sammet says:

    I looked a bit closer in the dimensions issue. Haven’t found an easy fix yet that works on Firefox and IE. Here a quick description on the functionality and problem:

    -balloon images are created with the give image (e.g. balloon-x.png).
    -The last one created is stored in the _lastBalloon property.
    -From the width and hight of that image the balloon dimensions are retrieved (this.balloonDimensions[0] = this._lastBalloon.width; this.balloonDimensions[1] = this._lastBalloon.height;).
    -depending on the position, one of the balloon images is used as a background image in a div tag:
    <div id=”anonymous_element_1″ style=”position: absolute; left: 223px; top: 70px; width: 450px; height: 360px; background: url("http://localhost/balloon/balloon-1.png&quot ;) no-repeat scroll left top transparent; display: block;”>

    From my testing, IE (IE7) seems to resize the image to the size of the div tag. Firefox doesn’t seem to. My thought is that we might be able to dynamically resize the image if we put it in an image tag and use z-index. Any other suggestions?
    Don’t have the time right now to work on this. I can live with using larger balloons but it would be nice if it would work down the road.

  130. Gunter Sammet says:

    Finally I managed to add the mouseout event. For some reason using the parameter:

    useEvent: ['mouseover', 'mouseout'],

    didn’t work. Checking the source I came up with the following solution:

    var tt_tag_5_3980 = new HelpBalloon({
    useEvent: ['mouseover'],
    balloonDimensions : [450,360],
    altText: ‘Click here to see more information for “Deck length”‘,
    dataURL: ‘product-finder-help.php?id=5&data_type=tag&language_id=1′
    Event.observe(tt_tag_5_3980.icon, ‘mouseout’, tt_tag_5_3980.toggle.bindAsEventListener(tt_tag_5_3980));

    As a side comment, to be able to use the altText, you will need to tweak the source code as well. Around line 268 add the title parameter to the img element:

    this.icon = new Element(‘img’, {
    src: this.options.icon,
    title: this.options.altText,
    id: “_icon”

    Hope that helps others to implement the solutions faster. The other solutions I found, didn’t work for me. Above solution uses HelpBalloon Version 2.0.1, Scriptaculous Version 1.8.2 and Prototype Version: ’′

  131. Pingback: imageSwap Bildgrsse

  132. Joe says:

    Any way of displaying a table in help balloon?

  133. Pete says:

    Looks nice and works nice but try to change anything (like the balloon dimensions then you are REALLY stuck.

    As someone once said “why make it easy if you can make it really complicated”

    … Oh – I know your answer! No need to reply – little einstein ;-)

    • Beau says:

      Actually, the way I did it *is* easier. Slicing a skin and getting it to scale the background of the balloon is the hard part, and was beyond my scope/need of this component. However, I am working on an advanced skinning techinque in the next version.

  134. Vivek says:


    Under “HelpBalloon.js 2.0.1 Advanced Examples” page i clicked on “Using HTML to populate a balloon” help icon… but it gives me error on IE-7 .

    The Error it gives: “The data necessary to complete this operation is not yet available” it works fine with “Mozilla Firefox”…

    Can you suggest me what might me the issue ?


  135. Pingback: FREE..! Tooltips Scripts (AJAX, Javascripts, CSS) Plus Tutorial |

  136. Yuriy says:

    Very nice library!
    But incompatible with jquery. This is very bad = (

    I’ve got a collision: if put jquery inclusion before prototype.js inclusion doesn’t work jquery else viceversa if put jquery inclusion after prototype.js inclusion doesn’t work prototype.js

    Can you help me? please …

    • Beau says:

      Unfortunately this is just an incompatibility between the two frameworks, probably due to name overlaps in some of the functions ( $() for instance ). I’m not sure what the work around would be. I am working on a jquery-compatible version of this component though.

    • Vimm says:

      Yup, it’s a well known incompatibility since both libraries use $ as an alias. There are ways around it though. If you include jquery after prototype and then call jQuery.noConflict() both libraries will work, but you will need to substitute “jQuery” for “$” in all of your code.

  137. Detlef says:

    I just tried it first time and had a problem the Balloon staying under the object.
    I solved it by appending ‘zIndex’: ’1000′ at several Element.setStyle positions (lines 560 – 585, 608, 742 -785) .
    Be carefull, must be zIndex not z-index

    now the ballon apears above all elements.

  138. Irishmaninusa says:

    Any word on if you converted this to jquery or if there is a plugin that is very similar to how this works.

  139. Vimm says:

    Just a heads up, but I noticed that HelpBalloon 2.0 uses document.getElementsByClassName which was deprecated in prototype 1.6, and has been removed as of 1.6.1.

  140. koçluk says:

    thank you very much for this flexible and well-documented tooltip!

  141. msprod says:

    hello, i’m french
    i have probleme with php and HelpBalloon :

    code :

    $code = <<<CODE

    var hb3 = new HelpBalloon({
    content: ‘ ‘
    + ‘Le:’


    result :<? echo Array ["title"];

    any want help me please ?

    verry Thanks to all

  142. msprod says:

    hello, i’m french
    i have probleme with php and HelpBalloon :

    code :

    $code = <<<CODE

    var hb3 = new HelpBalloon({
    content: ' '
    + 'Le:'


    result :<? echo Array ["title"];

    any want help me please ?

  143. Corbin says:

    I’m trying to assign the tool tip to 3 different images but it can only be applied to one image :/

  144. Ram says:

    set the property in Helpballon.js
    this.balloonDimensions[0] = 250;
    this.balloonDimensions[1] = 180;
    Here 250 width and 180 height. this will help you to resize your balloon. Also its better if you use the images of same dimention as mentioned aboue for ballon.

  145. Pingback: jQuery tooltip scripts, 100+ best

  146. Pingback: 50 Adet Tooltip Uygulaması

  147. Pingback: 1 step web design

  148. Pingback: 50 Useful Free jQuery Tooltip Plugins | Free and Useful Online Resources for Designers and Developers

  149. Dwijayasblog says:

    Thanks, it make my web looks more informative.

  150. Pingback: 30 Tooltip техник использующих JavaScript, Ajax и CSS | Интернет журнал Web 2.0 - Всё о Бизнесе в Сети

  151. Pingback: Tooltips |

  152. Henning says:

    Hi, I had some trouble implementing your library with prototype version 1.7

    Unfortunately I have quite a few problems even getting to debugging the js-code, since firebug crashes during the attempt. Can u help? Is there an implementation for prototype 1.7? I wouldn’t want to use an older version of prototype, since I am not sure what it might do to the rest of my code.

    Thanks in advance

  153. EngKiat says:

    Help, I can’t get the bubble image in the downloaded sample to show no matter which browser i use – tried FF11, IE10, Chrome 17 is there something missing?

    Many thanks!

  154. Pingback: 40 Useful jQuery Tooltip Scripts | Web Design Burn

  155. Pingback: We Are Twet ! » 37 Tooltips Scripts Dengan Ajax, JavaScript, CSS & html

  156. Pingback: 40 полезных jQuery скриптов всплывающих подсказок. : Tyupin K.

  157. Anne says:

    very great work! Thank you for this ToolTip Framework.
    I’m a JavaScript rookie and have a little issue with this Script. Is it posible to add a onclick-option to the close-button?

    I need something like this:

    Because I want, that if I click on one Icon, it will appear colored, otherwise it will be monochrome. If I close the bubble it should be monochrome again, to show the bubble for this icon is disabled.

    I found the follow code snipped in HelpBalloon.js:

    this.button = new Element('img', {
    src: this.options.button

    I guess there is the point where the button will be build. Right?
    If I change the code like followed, nothing happens anymore, no bubble will be shown, so I think my way was incorrect.

    for(var i = 0; i < 6; i++)
    this.button = new Element('img', {
    src: this.options.button
    onclick: this.document.getElementById(' "icon_" + i ').src = ' images/"icon_" + i + "_grey.png" '

    Could you give me some advice to solve my problem, please?
    That would be nice. Thank you very much.

    Best regards,

  158. Shivayan says:

    Can anyone give me the entire source code on these tool tip?? the code should include the html or jsp page. I am new to all these and i just can’t understand how to use the above mentioned scripts. Please help

  159. Home Page says:

    Spot on with this write-up, I actually believe this website needs a lot more attention.
    I’ll probably be back again to see more, thanks for the advice! Check out my website to get more info about forex, if you like.

  160. Pingback: 分享40个jQuery工具提示插件 : 免费资源分享站

  161. mike says:

    Hi, I’ve been searching for something similar to this, without having to write one myself. I wanted to use this for interactive help, such that the user can complete certain actions and have the tooltips display interactively.

    I especially like the resourced html file to load the tooltip content. I haven’t installed the tooltip myself, so I might be able to figure this out on my own, but I still want to ask. Would there be a way to use an external html source with multiple comments loaded, and then each tooltip instance would have a certain ‘tag’, which would then parse out part of the html file? I saw the ‘xml’ source example, and this might work, with a new element representing specific ‘tags’.

    Great work!

  162. Jesse Chisholm says:

    I realize you haven’t made an update in awhile, but this is how I use HelpBalloons.

    1: modify HelpBaloon.js by adding these lines to _draw (circa line 737)

    // 2013.01.07 - Jesse Chisholm - add possibility of tooltip indirecting
    // to hidden DIV in this page.
    // My Balloon Contents.
    // var tt1 = new HelpBalloon({
    // title:"Information",
    // content:"#MyBalloonDiv"
    // });
    if ('#' == this.options.content.charAt(0))
    var indirect = document.getElementById(this.options.content.substring(1));
    if (indirect)
    this.content.innerHTML = indirect.innerHTML;

    Which lets me have complex contents in the same page easily.

    Thanks for the useful script.

  163. kariniu60 says:

    Porn blog :
    gay older men porno amanda cory nude videos amateur squirt lesben sex videos kostenlos auf psp ohne download fuck mom.3gp arzu okay xxx free sex poro porno duro xxx

  164. Assir says:

    helpballoon is not working with IE 10, it would be very interesting is you guy could fix this. Tks a lot

  165. Mark Burke says:


    I have been using HelpBalloon.js, and it has been working perfectly in Internet Explorer, Firefox & Chrome, but since the latest release of IE10, the bubble image doesn’t render. Is this an issue with IE10 or HelpBalloon.js? Also is this code still being maintained?


  166. kote says:


    I an using IE 7 for my project.

    All the Help Balloons were displaying just behind the Accordions so cant able to read the content in the help balloons. How can I fix this issue ? I have added z-index for var container style { } and it works in google chrome. But all the users have IE 7 and its not working. Can anyone help me in this issue

  167. Luc Praetor says:

    Dude, great widget.

    But your prototype file… you have to use more distinct names. Imagine how many of your javascript functions will clash with other people’s web apps/websites if they just plug in this code.

    Javascript is holy. It requires respect. Distinct names, please.

    • Beau says:

      I agree, and it’s something I need to fix. I’m moving all my repos over to github, and as part of that I plan on namespacing all of my projects to BeauScott.(/(AutoComplete)|(RatingStars)|(HelpBalloons)/) soon.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>