Tipsy

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

Examples & Usage

Basic

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

Gravities

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

$('#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.

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

Fading

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

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

Bonus Feature

Slightly Advanced Usage

$('#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('data-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 });

Custom Classes

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

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

Show/Hide Delay

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

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 data-title attribute instead (this only applies if you're using the title attribute).

Using Tooltips on Form Inputs

By default, tooltips are bound to both mouse and keyboard interactions - mouseenter/mouseleave and focus/blur. If you want to just bind the tooltip to focus/blur (for instance for form controls), you can set the option {trigger: 'focus'}:

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

Manually Triggering a Tooltip

It's possible to disable hover/focus 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>

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.

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

Support for ARIA attributes

ARIA attributes are supported using the option {aria: true}. The tooltip trigger must have a parent set to role="application" or role="document" and the tooltip should be enabled on focus (screen reader users are most likely to be using the keyboard).

The tooltip will be set to role="tooltip" and the trigger will be linked to the tooltip with aria-describedby (using a generated ID).

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

Summary of Configuration Options

$.fn.tipsy.defaults = {
    aria: false,      // add ARIA attributes? (note dependencies)
    className: null,  // custom class to add to tooltip (string or function)
    id: 'tipsy',      // specific id to give to the generated tooltip
    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: 'interactive'  // how tooltip is triggered - 'interactive' for hover and focus | 'focus' for focus only | 'bind' for bind only | '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'.

Northwest	North	Northeast
West		East
Southwest	South	Southeast

tipsy - Facebook-style tooltip plugin for jQuery

Overview