Tipsy is a jQuery plugin for creating a Facebook-like tooltips effect based on an anchor tag's title attribute.
By default, tooltips will appear centred underneath their anchor:
$('#example-1').tipsy();
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 |
$('#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$('#foo').tipsy({gravity: $.fn.tipsy.autoNS});
For full Wob2.0 compliance, you must fade these badboys in:
$('#example-fade').tipsy({fade: true});
You can EVEN COMBINE FADE AND GRAVITY! (exercise for reader)
Tooltip text can be set based on any attribute, not just title
:
$('#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:
$('#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:
$('#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):
$('#example-html').tipsy({html: true });
This className
option can be used to add extra CSS classes to generated
tooltips:
$('#example-custom-class').tipsy({className: 'red'});
$('#example-delay').tipsy({delayIn: 500, delayOut: 1000});
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).
Tooltips can be bound to form inputs' focus/blur events using the option
{trigger: 'focus'}
:
<script type='text/javascript'> $(function() { $('#focus-example [title]').tipsy({trigger: 'focus', gravity: 'w'}); }); </script>
It's possible to disable hover events and instead trigger tooltips manually:
<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>
Live events are supported using the option {live: true}
.
jQuery ≥ 1.4.1 is required and live tooltips do not support manual triggering.
<script type='text/javascript'> $('a.live-tipsy').tipsy({live: true}); </script>
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 };
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.
Package downloads are available from the Github project page - select the latest version from the 'Switch Tags' menu then click 'Downloads'.
jason@donut ~ $ git clone git://github.com/jaz303/tipsy.git