BeautyTips Demo

BeautyTips 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 jQuery.com. 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.

Usage

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

Versions

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

Examples

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

No options

hover

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.

$('#example1').bt();

Content from argument

click

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.

Pre/post functions

hover

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.

CSS tricks

hover

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.

Customizing the balloon

hover

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.

Image content

hover

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.

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.

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.

HoverIntent

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.

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.

Big Big Big

click

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.

Simple Animation

hover

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.

Complex Animation

hover

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.

Drop Shadows

hover

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.

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.

Options

A full list of options can be found at the bottom of the jquery.bt.js 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="jquery.bt.js"...):

Wrap up

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.