BeautyTips Demo

BeautyTipsBeautyTips is a jQuery tooltips plugin which uses the canvas drawing element in the HTML5 spec to dynamically draw tooltips (sometimes called "talk bubbles" or "help balloons") associated with a html element on the page. These tips are highly configurable and can be triggered in many different ways.

The canvas element is supported in modern versions of FireFox, Safari, and Opera. However, Internet Explorer needs a separate library called ExplorerCanvas included on the page in order to support canvas drawing functions. ExplorerCanvas was created by Google for use with their web apps and you can find it here.

BeautyTips was written to be simple to use and pretty. All of its options are documented at the bottom of the .js file and defaults can be overwritten globally for the entire page, or individually for each target element (more about this in the wrap up section).

BeautyTips has been tested with jQuery 1.2.6 and 1.3 on Firefox 3.x, Safari 3.x (also works on iPhone!), IE 6.x+, and Opera 8+, but I'm sure other canvas-capable browsers will work as well.

By default each tooltip will be positioned on the side of the target element which has the most free space. This is affected by the scroll position and size of the current window, so each Beauty Tip is redrawn each time it is displayed. It may appear above an element at the bottom of the page, but when the page is scrolled down (and the element is at the top of the page) it will appear below it. Additionally, positions can be forced or a preferred order can be defined. See examples below.

Project Page and Download

BeautyTips has a page in the plugins directory on This is where you can download the latest version. It is also the best place to post bugs and feature requests.

Other helpful plugins

To fix z-index problems with form elements in IE6, include the bgiframe plugin on your page. BeautyTips will automatically recognize it and use it.

BeautyTips also works with the hoverIntent plugin see hoverIntent example below for usage.


The function can be called in a number of ways.
$(selector).bt('Content text');
$(selector).bt('Content text', {option1: value, option2: value});
$(selector).bt({option1: value, option2: value});


This demo page is using version of jQuery and version of BeautyTips.


Note: html and javascript textareas are live. Feel free to experiment with the code and see how BeautyTips are affected.

No options


This is the simplest example. No arguments are sent and the default settings are used to create a tip which appears on the side with the most space.


Content from argument


Tip appears above the element when it is clicked. The contents of tip is provided when creating the tip.

$('#example2').bt('Contents of the tip is provided in the .bt() call', {trigger: 'click', positions: 'top'});

Content from attribute

This example uses the contentSelector attribute to determine where the content comes from. In this case the selector is $(this).attr('href') and the content is the href attribute of the hovered link. Other options define a red balloon with bold white text. The box will be a variable width up to 400px ("width: 'auto' in cssStyles makes text box shrink-to-fit) with rounded corners. The script will try to position the box to the left, then to the right, and finally it will place it on the bottom if it does not fit elsewhere.

$('#example3').bt({ contentSelector: "$(this).attr('href')", fill: 'red', cssStyles: {color: 'white', fontWeight: 'bold'}, shrinkToFit: true, padding: 10, cornerRadius: 10, spikeLength: 15, spikeGirth: 5, positions: ['left', 'right', 'bottom'] });

Pre/post functions


There are four different functions which can be triggered at different points in the lifetime of a beautyTip: preShow, postShow, preHide, and postHide.

In this example, a function is triggered to change the content of the target element before the tip is shown. After the tip is hidden, another function changes the content back. this in these function refers to the target element. These functions could be used for just about anything.

$('#example4').bt({ preShow: function() { $(this).data('origContent', $(this).html()); $(this).html('hovering active'); }, postHide: function() { $(this).html($(this).data('origContent')); } });

CSS tricks


When the BeautyTip is active, an additional class is added to the target element. This class, called "activeClass", can be defined when calling the bt() function. Additionally, each BeautyTip popup has a wrapper div which surrounds its content. The class on this div is also definable.

Note that the BeautyTip "balloon" itself is drawn as a bitmap using canvas methods and functions similar to an <img> element, so it can not be affected by CSS. There are many options for changing this element using JavaScript options though.

$('#example5').bt({ activeClass: 'example-5-active', cssClass: 'example-5-tip' });

Customizing the balloon


The BeautyTip balloons are drawn dynamically and highly configurable. Customizable attributes include background color and opacity, stroke width and color, spike length and width, corner radius, and more. For convenience, style attributes such as font color and weight can be sent through the JavaScript call as well.

$('#example6').bt({ padding: 20, width: 100, spikeLength: 40, spikeGirth: 40, cornerRadius: 40, fill: 'rgba(0, 0, 0, .8)', strokeWidth: 3, strokeStyle: '#CC0', cssStyles: {color: '#FFF', fontWeight: 'bold'} });

Image content


Images can be loaded into the BeautyTip. You should, however, add width and height attributes (or use CSS for this) so that the browser will know what size to "save space for" as the image loads.

This example also uses some special triggers so that the tip appears on mouseover, but disappears using click. BeautyTips' default clickAnywhereToClose option also allows the user to click anywhere in the document (outside of the tip) in order to close it. This can be disabled either globally or per tip.

$('#example16').bt('', { width: 200, fill: 'white', cornerRadius: 20, padding: 20, strokeWidth: 1, trigger: ['mouseover', 'click'] });

Customizing triggers

The trigger is what causes the tip to appear/disappear. The default option is 'hover', which will trigger the tip when the mouse hovers over an element. If the hoverintent plugin is installed (as on this page), that will become the default trigger and there will be slight (but configurable) delay before the tip appears.

In this example, the trigger events for this textfield are 'focus' and 'blur'. This means that the tip will get triggered even if the user uses the tab key to enter/leave this form field.

$('#example7').bt({ trigger: ['focus', 'blur'], positions: ['right'] });

Customizing triggers 2

In this example, 'keyup' triggers the display of the tip while 'blur' removes it. This means that the tip won't appear until the user actually changes the field (using the keyboard).

The full list of trigger events are: blur, focus, load, resize, scroll, unload, click, dblclick, mousedown, mouseup, mousemove, mouseover, mouseout, mouseenter, mouseleave, change, select, submit, keydown, keypress, keyup, and error. However not all events are available for all elements (see: events documentation).

$('#example8').bt({ trigger: ['keyup', 'blur'], positions: ['right'] });

Scripting on/off

no trigger

This tip is initiated with a trigger of 'none'. All of the options are set, but turn on/off of the tip isn't bound to any event. We can, however, turn on and off the tip using Javascript. $('#example15').btOn(); turns it on. $('#example15').btOff(); turns it off. These btOn() and btOff() functions are available for all elements which have been set up using the bt() function. So, we can programmatically turn on any BeautyTip on the page. Click here to turn on the tip from the previous example.

$('#example15').bt({ trigger: 'none', contentSelector: "$('#example-15-content')", width: 400 });


hover and wait

The hoverIntent plugin allows control over how and when the mouseOver event gets triggered when a user hovers over an element. In this example, the interval has been cranked up to 1 second, so the user needs to hover for almost a second before the tip appears. The timeout has been raised to 2 seconds so the tip will remain visible for that long before disappearing.

$('#example9').bt({ hoverIntentOpts: { interval: 1000, timeout: 2000 } });

Ajax content


Content comes from the #content div of the html page: demo-ajax.html. Note: this isn't really ajax, it's actually ahah (asynchronous HTML and HTTP). Ahah is much easier to deal with than ajax (which technically uses XML).

$('#example10').bt({ ajaxPath: 'demofiles/demo-ajax.html div#content' });

Ajax error


Requested ajax page doesn't exist. This example uses a custom error message. This example may not work correctly if you have opened the file locally (without a web server).

$('#example11').bt({ ajaxPath: 'foo.html', ajaxError: "Egads! There was a problem getting this content. Here's what we know: %error." });

Ajax dynamic path

AjaxPath is being read from the 'href' value of the link. This is accomplished by defining the ajaxPath as an array. The first value of the array is the jQuery code to find the path value (in this case "$(this).attr('href')"). The optional second value of the array is the content selector within the loaded page (in this case 'div#content'). This is a handy way of adding "preview" BeautyTips to a bunch of links on a page.

$('#example18').bt({ ajaxPath: ["$(this).attr('href')", 'div#content'] });

Big Big Big


A popup with lots of content. This popup gets populated from a div which immediately follows this text in the html source, but gets hidden by the same script which defines the BeautyTip. This is a good way to provide degradable help which appears for users with JavaScript disabled.

A really big popup

This tip is chock-full of content. It is intended to show how BeautyTips deals with fitting large content onto the page. The rest of this content is gibberish. Seamlessly empower dynamic communities with clicks-and-mortar testing procedures. Globally scale front-end ideas through next-generation web services. Holisticly harness business data via resource maximizing meta-services.

Assertively pontificate extensible ROI via end-to-end manufactured products. Compellingly scale resource sucking human capital rather than visionary infomediaries. Quickly evolve robust data with intuitive vortals.

Authoritatively revolutionize scalable solutions without e-business intellectual capital. Compellingly restore web-enabled potentialities through tactical information. Phosfluorescently disintermediate stand-alone convergence for team building sources.

Interactively leverage existing sticky products rather than orthogonal expertise. Enthusiastically innovate worldwide process improvements whereas proactive markets. Appropriately evisculate B2B niche markets before vertical content.

Quickly reinvent state of the art potentialities after process-centric experiences. Completely e-enable sticky technology whereas impactful ideas. Dynamically underwhelm holistic "outside the box" thinking whereas effective testing procedures.

Synergistically plagiarize cost effective leadership and low-risk high-yield e-commerce. Credibly maintain market positioning strategic theme areas and client-based benefits. Globally disseminate clicks-and-mortar infomediaries for premium e-tailers.

Professionally reconceptualize interdependent content through error-free innovation. Collaboratively provide access to one-to-one strategic theme areas without magnetic web-readiness. Appropriately negotiate strategic opportunities without timely alignments.

Continually engineer premier best practices after plug-and-play communities. Monotonectally drive installed base users whereas wireless products.

$('#example-14-content').hide(); $('#example14').bt({ trigger: 'click', contentSelector: "$('#example-14-content').html()", /*get text of inner content of hidden div*/ width: 500, fill: '#00FF4E', strokeWidth: 0, /*no stroke*/ spikeLength: 40, spikeGirth: 10, padding: 20, cornerRadius: 15, cssStyles: { fontFamily: '"lucida grande",tahoma,verdana,arial,sans-serif', fontSize: '13px' } });

Simple Animation


Animation can be added by creating a custom showTip or hideTip function. Each function gets an argument of box, which is a reference to the .bt-wrapper div around the tip. The box element is set to display: none, so your code will presumably use animation methods to show it. The this variable in each function refers to the target (hovered, clicked, focused, etc) element. The hideTip function gets a second argument of callback. This is a reference to the cleanup function and MUST be triggered at the end of the hideTip animation.

It appears that this animation doesn't work correctly in Internet Explorer. This is most likely a bug somewhere between jQuery and Explorer Canvas. It does degrade to non-animated functionality though. Ironically, the complex animation example below works better in IE.

$('#example21').bt({ showTip: function(box){ $(box).fadeIn(500); }, hideTip: function(box, callback){ $(box).animate({opacity: 0}, 500, callback); }, shrinkToFit: true, hoverIntentOpts: { interval: 0, timeout: 0 } });

Complex Animation


At the time that showTip is triggered, the tip is hidden (display: none) but completely built, positioned, and ready to go. If we want to animate its position, size, or other attributes, we need to create variables representing the current attributes so that we know where to end our animation. In this example, we're animating the size of the canvas (the bitmap drawing of the tip) as well as it's left and top position so that it remains centered as its size animates.

In order to keep the animation efficient, the content (the text) is hidden during the animation and appears after the animation is finished.

hideTip works in reverse. The callback gets called at the end of the animation to cleanup the box, removing it from the DOM and getting things ready for the next time the tip is triggered.

$('#example20').bt({ showTip: function(box){ var $content = $('.bt-content', box).hide(); /* hide the content until after the animation */ var $canvas = $('canvas', box).hide(); /* hide the canvas for a moment */ var origWidth = $canvas[0].width; /* jQuery's .width() doesn't work on canvas element */ var origHeight = $canvas[0].height; $(box).show(); /* show the wrapper, however elements inside (canvas, content) are now hidden */ $canvas .css({width: origWidth * .5, height: origHeight * .5, left: origWidth * .25, top: origHeight * .25, opacity: .1}) .show() .animate({width: origWidth, height: origHeight, left: 0, top: 0, opacity: 1}, 400, 'easeOutBounce', function(){$} /* show the content when animation is done */ ); }, /* when using hideTip, do NOT forget 'callback' at end of animation */ hideTip: function(box, callback){ var $content = $('.bt-content', box).hide(); var $canvas = $('canvas', box); var origWidth = $canvas[0].width; var origHeight = $canvas[0].height; $canvas .animate({width: origWidth * .5, height: origHeight * .5, left: origWidth * .25, top: origHeight * .25, opacity: 0}, 400, 'swing', callback); /* callback */ }, /* other options */ shrinkToFit: true, hoverIntentOpts: { interval: 0, timeout: 0 } });

Drop Shadows


Drop shadows are part of the canvas spec, but they are not implemented by many browsers. Drop shadows currently only work in Safari and Firefox 3.5 and higher. Eventually I would like to create canvas-drawn drop shadows that should work in all browsers, but for the time being, keep in mind that these won't work in all browsers. However, for these non-drop-shadow browsers, you can define "no shadow options" (noShadowOpts) to define how the tip should be displayed if shadows aren't supported.

$('#example19').bt('Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Morbi commodo, ipsum sed pharetra gravida, orci magna rhoncus neque, id pulvinar odio lorem non turpis.', { fill: '#FFF', cornerRadius: 10, strokeWidth: 0, shadow: true, shadowOffsetX: 3, shadowOffsetY: 3, shadowBlur: 8, shadowColor: 'rgba(0,0,0,.9)', shadowOverlap: false, noShadowOpts: {strokeStyle: '#999', strokeWidth: 2}, positions: ['left', 'top'] });

Netflix style


Netflix-style big descriptive popups using ajax.

$('#example13').bt({ ajaxPath: 'demofiles/netflix.html', centerPointY: .1, positions: ['right', 'left'], padding: 0, width: 256, spikeGirth: 60, spikeLength: 50, cornerRadius: 10, fill: '#FFF', strokeStyle: '#B9090B', shadow: true, shadowBlur: 12, shadowOffsetX: 0, shadowOffsetY: 5, hoverIntentOpts: {interval: 800, timeout: 0}, cssStyles: { fontSize: '12px', fontFamily: 'arial,helvetica,sans-serif' } });

Google Maps


Google Maps balloons! Content is provided by a hidden div on the page. Note the use of centerPointX to adjust where the spike extends from. We're also using a close-box "x" image in the content which is a javascript link to close the tip.

123 Main St.
Seekonk, MA 02771
$('#example-17-content').hide(); $('#example17').bt({ positions: 'top', contentSelector: "$('#example-17-content')", /*hidden div*/ trigger: 'click', width: 220, centerPointX: .9, spikeLength: 65, spikeGirth: 40, padding: 15, cornerRadius: 25, fill: '#FFF', strokeStyle: '#ABABAB', strokeWidth: 1 });

Facebook style



$('#example12').bt({ fill: '#F7F7F7', strokeStyle: '#B7B7B7', spikeLength: 10, spikeGirth: 10, padding: 8, cornerRadius: 0, cssStyles: { fontFamily: '"lucida grande",tahoma,verdana,arial,sans-serif', fontSize: '11px' } });

Hulu style

BeautyTips: Pretty Tooltips For jQuery
Season 1, Ep. 1 (00:48)
Air date: 05/20/2009 | Rated: TV-14 | ☆☆☆☆☆

Call them tooltips, talk bubbles, or help balloons, we're making them quick and pretty - without any graphics slicing or careful CSS layering.

Hulu style. Use Safari or Firefox 3.5+ to get the full effect with the drop shadow.

$('#hulu-content').hide(); $('#hulu-target').bt({ contentSelector: "$('#hulu-content')", positions: ['right', 'left'], fill: '#F4F4F4', strokeStyle: '#666666', spikeLength: 20, spikeGirth: 10, width: 350, overlap: 0, centerPointY: 1, cornerRadius: 0, cssStyles: { fontFamily: '"Lucida Grande",Helvetica,Arial,Verdana,sans-serif', fontSize: '12px', padding: '10px 14px' }, shadow: true, shadowColor: 'rgba(0,0,0,.5)', shadowBlur: 8, shadowOffsetX: 4, shadowOffsetY: 4 });


A full list of options can be found at the bottom of the file itself. Scroll to the bottom of the file to see the list of options along with their default values and a short descriptions of what each one does.

These defaults can be overridden during each call to the $.bt() function (as in the examples above) or they can be overridden globally for all BeautyTips on the page. For instance, to change the ajax loading content for all BeautyTips on the page, you could insert the following code into your document's <head> (somewhere after <script src=""...):

<script language="JavaScript"> = '<img src="/images/throbber.gif" width="40" height="40" />'; = true;

Wrap up

Found bugs and/or want to contribute to development? Please use the issue queue on

Twitter: I tend to post about BeautyTips development on Twitter, so follow me if you'd like to keep up with the latest news.

IRC: I also tend to hang out in the #jQuery IRC room (username: jjeff). If you've got quick questions about BeautyTips, try to find me there.

Is BeautyTips saving you money and development time on your project? Do you feel compelled to reward its developer for his hard work and encourage further development? Well you could certainly buy him something from his Amazon wish list.

It's always encouraging to hear from people using BeautyTips for cool and/or notable things. Just send a note to . I'd love to hear from you. Please do not email me with support requests. Those should go to the issue queue.

- Jeff Robbins