Overview

Tipsy is a jQuery plugin for creating a Facebook-like tooltips effect based on an anchor tag's title attribute.

Examples & Usage

Basic

By default, tooltips will appear centred underneath their anchor:

Hover over me

Basic example:
$('#example-1').tipsy();

Gravities

Using the gravity parameter, it's possible to control the positioning of the tooltip relative to the pointee:

Northwest North Northeast
West   East
Southwest South Southeast
Gravity example:
$('#foo').tipsy({gravity: 'n'}); // nw | n | ne | w | e | sw | s | se

As of version 0.1.3, it's possible to use a callback function to set the gravity dynamically at hover-time. Within the callback, this refers to the active element, and the function should return the calculated gravity as a string. Two demo callbacks are supplied - $.fn.tipsy.autoNS and $.fn.tipsy.autoWE - which select north/south and west/east gravity, respectively, based on the element's location in the viewport.

Here's an example (scroll the page to see the effect):

Dynamic Gravity
Dynamic gravity example:
$('#foo').tipsy({gravity: $.fn.tipsy.autoNS});

Fading

For full Wob2.0 compliance, you must fade these badboys in:

Hover over me

Fade example:
$('#example-fade').tipsy({fade: true});

Bonus Feature

You can EVEN COMBINE FADE AND GRAVITY! (exercise for reader)

Slightly Advanced Usage

Tooltip text can be set based on any attribute, not just title:

Hover over me

Custom attribute example:
$('#example-custom-attribute').tipsy({title: 'id'});

If any attribute isn't good enough, you may pass a callback function instead. It should return the tooltip text for this element:

Hover over me

Callback example:
$('#example-callback').tipsy({title: function() { return this.getAttribute('original-title').toUpperCase(); } });

Finally, it is possible to specify a fallback tooltip for any element which does not have any tooltip text:

Hover over me

Fallback example:
$('#example-fallback').tipsy({fallback: "Where's my tooltip yo'?" });

If your tooltip content contains HTML, set the html option to true (relies on invalid HTML, sorry):

Hover over me

HTML example:
$('#example-html').tipsy({html: true });

Custom Classes

This className option can be used to add extra CSS classes to generated tooltips:

Custom class example:
$('#example-custom-class').tipsy({className: 'red'});

Try me out

Show/Hide Delay

Delay example:
$('#example-delay').tipsy({delayIn: 500, delayOut: 1000});

Hover and wait

Dynamically Updating Text

Tipsy tooltips are 'live' - if the source attribute's value changes, the tooltip text will be updated the next time the tooltip is shown. There's one caveat - if you wish to remove the tooltip by setting the title attribute to an empty string, set the original-title attribute instead (this only applies if you're using the title attribute).

Dynamic updating example:
Hover over me | New tooltip text:

Using Tooltips on Form Inputs

Tooltips can be bound to form inputs' focus/blur events using the option {trigger: 'focus'}:

Form input tooltips example:



Form input tooltips code:
<script type='text/javascript'>
  $(function() {
    $('#focus-example [title]').tipsy({trigger: 'focus', gravity: 'w'});
  });
</script>

Manually Triggering a Tooltip

It's possible to disable hover events and instead trigger tooltips manually:

Manual triggering example:
My tooltip is manually triggered | Show it | Hide it
Code for manual triggering:
<p id='manual-example'>
  <a rel='tipsy' title='Well hello there'>My tooltip is manually triggered</a>
  <a href='#' onclick='$("#manual-example a[rel=tipsy]").tipsy("show"); return false;'>Show</a>
  <a href='#' onclick='$("#manual-example a[rel=tipsy]").tipsy("hide"); return false;'>Hide</a>
</p>

<script type='text/javascript'>
  $('#manual-example a[rel=tipsy]').tipsy({trigger: 'manual'});
</script>

Support for Live Events

Live events are supported using the option {live: true}. jQuery ≥ 1.4.1 is required and live tooltips do not support manual triggering.

Live events example:

Code for live events:
<script type='text/javascript'>
  $('a.live-tipsy').tipsy({live: true});
</script>

Summary of Configuration Options

Here is the default options declaration: 

$.fn.tipsy.defaults = {
    className: null,  // custom class to add to tooltip (string or function)
    delayIn: 0,       // delay before showing tooltip (ms)
    delayOut: 0,      // delay before hiding tooltip (ms)
    fade: false,      // fade tooltips in/out?
    fallback: '',     // fallback text to use when no tooltip text
    gravity: 'n',     // gravity (string or function)
    html: false,      // is tooltip content HTML?
    live: false,      // use live event support?
    offset: 0,        // pixel offset of tooltip from element
    opacity: 0.8,     // opacity of tooltip
    title: 'title',   // attribute/callback containing tooltip text
    trigger: 'hover'  // how tooltip is triggered - hover | focus | manual
};

Notes

Tipsy needs to erase any existing value for an element's title attribute in order to suppress the browser's native tooltips. It is stashed in the element's original-title attribute in case you need to retrieve it later.

As of version 0.1.4, the tooltip text is recomputed on every hover event so updating the title attribute will have the expected effect.

Download

Package

Package downloads are available from the Github project page - select the latest version from the 'Switch Tags' menu then click 'Downloads'.

github

jason@donut ~ $ git clone git://github.com/jaz303/tipsy.git