Tooltipster – The jQuery Tooltip Plugin

Options

Advanced

The awesomesauce Tooltipster API

The Tooltipster API was created to be as flexible and easy to use as possible (thanks to glebtv for the inspiration). The API allows you to create custom triggers, update tooltip content on the fly (whether the tooltip is currently open or not), destroy Tooltipster functionality if needed, and reposition tooltips for unique use cases.

Here is a quick look at all of the API methods:

// set default options for all future tooltip instantiations
$.fn.tooltipster('setDefaults', {
  position: 'bottom'
});

// show a tooltip (the 'callback' argument is optional)
$(...).tooltipster('show', callback);

// hide a tooltip (the 'callback' argument is optional)
$(...).tooltipster('hide', callback);

// temporarily disable a tooltip from being able to open
$(...).tooltipster('disable');

// if a tooltip was disabled from opening, reenable its previous functionality
$(...).tooltipster('enable');

// hide and destroy tooltip functionality
$(...).tooltipster('destroy');

// return a tooltip's current content (if selector contains multiple origins, only the value of the first will be returned)
$(...).tooltipster('content');

// update tooltip content
$(...).tooltipster('content', myNewContent);

// reposition and resize the tooltip
$(...).tooltipster('reposition');

// return the HTML root element of the tooltip
$(...).tooltipster('elementTooltip');

// return the HTML root element of the icon if there is one, 'undefined' otherwise
$(...).tooltipster('elementIcon');

Using AJAX to generate your tooltip content

Tooltipster gives you the ability to fire a custom synchronous or asynchronous function everytime before the tooltip launches (functionBefore) or just once upon instantiation (functionInit). One great use for this is to grab dynamic content for your tooltips via AJAX.

Here is an example of using functionBefore() asynchronously to replace a loading notification with our AJAX call. Once the content has been retrieved and updated, we'll take advantage of setting $.data() to keep our content cached for the next time the tooltip is opened:

$('.tooltip').tooltipster({
    content: 'Loading...',
    functionBefore: function(origin, continueTooltip) {

        // we'll make this function asynchronous and allow the tooltip to go ahead and show the loading notification while fetching our data
        continueTooltip();
        
        // next, we want to check if our data has already been cached
        if (origin.data('ajax') !== 'cached') {
            $.ajax({
                type: 'POST',
                url: 'example.php',
                success: function(data) {
                    // update our tooltip content with our returned data and cache it
                    origin.tooltipster('content', data).data('ajax', 'cached');
                }
            });
        }
    }
});

However, maybe you just need to make one call and only need it to fire once instead of everytime the tooltip opens. This is where you could use functionInit(). This function will fire only once - right at the beginning of the instantiation process. You'll have the ability to do things like check the current content and set new content. Since the fancy API methods for returning and setting the value aren't instantiated yet, the way we go about this is a little different than functionBefore():

$('.tooltip').tooltipster({
    functionInit: function(origin, content) {
		
        if (content === 'This is bad content') {
            
            // when the request has finished loading, we will change the tooltip's content
            $.ajax({
                type: 'POST',
                url: 'example.php',
                success: function(data) {
                    origin.tooltipster('content', 'New content has been loaded : ' + data);
                }
            });
			
            // this returned string will overwrite the content of the tooltip for the time being
            return 'Wait while we load new content...';
        }
        else {
            // return nothing : the initialization continues normally with its content unchanged.
        }
    }
});

Manually show and hide a tooltip

By default and according to the 'trigger' option, Tooltipster automatically shows tooltips upon users' mouse clicks or mouse hovering (or their touch-gesture equivalents). In addition to this, you may also manually open or close a tooltip at anytime with a simple javascript command.

To achieve this, Tooltipster has the 'show' and 'hide' methods. Both of them may receive an optional 'callback' parameter, which represents a function you'd like to call when the tooltip is done animating.

Here's an example of how you could launch a specific tooltip on page load and close it when any key on your keyboard is pressed. This will still preserve the default hover trigger.

<span class="tooltip" id="example" title="My tooltip content">Example</span>

$(document).ready(function() {
   
   // first on page load, initiate the Tooltipster plugin
   $('.tooltip').tooltipster();
   
   // then immediately show the tooltip
   $('#example').tooltipster('show');
   
   // as soon as a key is pressed on the keyboard, hide the tooltip.
   $(window).keypress(function() {
      $('#example').tooltipster('hide');
   });
});

You may also provide a function as the callback parameter of the show/hide methods. The callback functions are called in the context of the tooltipstered element. Please note that if the show/hide action is somehow cancelled before it has completed, the callback function will never be called.

$(document).ready(function() {
   
   $('.tooltip').tooltipster();
   
   $('#example').tooltipster('show', function() {
       alert('The tooltip is now fully open. The content is: ' + this.tooltipster('content'));
   });
   
   $(window).keypress(function() {
      $('#example').tooltipster('hide', function() {
         alert('The tooltip is now fully closed');
      });
   });
});

Updating a tooltip's content

It's easy as pie to update a tooltip's content - whether it's open or closed. Depending on your selector, you can update multiple tooltips at once or just one:

$('#my-special-tooltip').tooltipster('content', 'My new content');

By default, Tooltipster will play a subtle animation when the content changes. To tweak the animation, check out the '.tooltipster-content-changing' class in your tooltipster.css file. It's important to note that only CSS transforms will be animated. To disable this animation, set updateAnimation to false.