API A full reference of qTip2 's inner workings

The API features extensive methods and attributes for use with non-basic implementations, and relates well with the Events documentation.

Accessing the API

The recommended method for gaining access to the API is via the target element. This can only be done after the .qtip() method has been previously called and the tooltip setup. For example:

// Create the tooltip first using regular .qtip() call
var tooltips = $('.selector').qtip({
    /* configuration options here */
});

// Grab the first element in the tooltips array and access its qTip API
var api = tooltips.qtip('api');

You can also gain access to the API via the tooltip element itself, with one important caveat. Tooltips are lazy-loaded into the DOM, so you must ensure that the tooltip is rendered before attempting to access the API, otherwise it won't work. You'll also need to assign an ID so you can easily identify it.

// Grab the API of a tooltip with an `id` of 'apiTest'
var api = $('#qtip-apiTest').qtip('api');

Update multiple API's

You can call any API method (detailed below) on multiple tooltip APIs simply by passing the method name as the first parameter to the .qtip() method:

$('.selector').qtip('reposition'); // Reposition all tooltips belonging to the selected elements
$('.selector').qtip('disable'); // Disable all tooltips belonging to the selected elements

Any subsequent arguments passed will be passed directly to the named API method, for example:

$('.selector').qtip('toggle', true); // Show  all tooltips belonging to the selected elements
$('.selector').qtip('destroy', true); // Immediately destroy all tooltips belonging to the selected elements

You can also use the jQuery UI-style option(s) method, which maps directly to the set and get methods:

// Get the content.text of the first matched element's tooltip
$('.selector').qtip('option', 'content.text');

// Set the content.text of all matched element's tooltips
$('.selector').qtip('option', 'content.text', 'New content');

// The above is equivilent to this long form
$('.selector').each(function() {
    $(this).qtip('api').set('content.text', 'New content');
});

Dot notation

Dot notation is a specific format of String used to reference nested object attributes.

// Example tooltip configuration object
var config = {
    id: 'sampletooltip',
    content: {
        text: 'Hi. I am a sample tooltip!',
        title: 'Sample tooltip'
    }
};

// Exampe dot notations
api.get('id'); // Returns 'sampletooltip'
api.get('content.text'); // Returns 'My content'
api.get('content.title'); // Returns 'Sample tooltip'

You'll need to use this notation when dealing with the .get() and .set() methods.


API Methods

.get()

Gets the current value of the specified option (represented in dot notation).

Signatures

.get(option)

option
Type: String
A string representing the configuration object's key you wish to change, in dot notation i.e. the name of the option

Dot notation

Dot notation is a specific format of String used to reference nested object attributes.

// Example tooltip configuration object
var config = {
    id: 'sampletooltip',
    content: {
        text: 'Hi. I am a sample tooltip!',
        title: 'Sample tooltip'
    }
};

// Example dot notations
api.get('id'); // Returns 'sampletooltip'
api.get('content.text'); // Returns 'My content'
api.get('content.title'); // Returns 'Sample tooltip'

.set()

Sets the value of the specified option (represented in dot notation) and updates all of the tooltip's relevant properties. An object may also be used to set multiple options at once.

Signatures

.set(option, value)

option
Type: String
A string representing the configuration object's key you wish to change, in dot notation i.e. the name of the option

value
Type: Various
A value to set the passed option name to, multiple types supported depending upon the option being set

.set(options)

options
Type: PlainObject
A map of key/value pairs, with the key representing an option in (dot notation), and its value being the value to set the option to.

Examples

// Single property
api.set('content.text', 'new content');

// Multiple properties
api.set({
    'content.title': 'New Title',
    'style.widget': true
});

.toggle()

Toggles the current visibility state of the tooltip.

Signatures

.toggle([state, event])

state (default: undefined)
Type: Boolean
A boolean representing the the visiblility state, hiding if false, showing if true. If not passed, it will invert the current visibility state.

event (default: undefined)
Type: Event
The event object, ideally passed when the method is called within an event handler.

Examples

// Will "toggle" the visiblitiy of the tooltip i.e. hiding it if currenty visible and vise-versa.
api.toggle();

// Show and hide the tooltip using boolean state value
api.toggle(true); // Show
api.toggle(false); // Hide

// Hide the tooltip when clicking these matched elements
$('.selector').click(function(event) {
    api.toggle(true, event); // Pass event as second parameter!
})

.show()

Helper method for calling .toggle(true).

Signatures

.show([event])

event (default: undefined)
Type: Event
The event object that caused the method call. Ideally passed when the method is called within an event handler.

.hide()

Helper method for calling .toggle(false).

Signatures

.hide([event])

event (default: undefined)
Type: Event
The event object that caused the method call. Ideally passed when the method is called within an event handler.

.disable()

Toggles the current interactive state of the tooltip i.e. whether it's disabled or not.

Signatures

.disable([state])

state (default: undefined)
Type: Boolean
A boolean representing the the disabled state i.e. true disables it, false enables it. If not passed, it will invert the current visibility state

Examples

// Disable the tooltip
api.disable(true);

// Enable it again
api.disable(false);

Notes

  • When disabled, the tooltip will not respond to any DOM events

.enable()

Helper method for calling .disable(false).

.reposition()

Updates the tooltip's position relative to the position.target element.

Signatures

.reposition([event, effect])

event
Type: Event
The event object that caused the method call. Ideally passed when the method is called within an event handler.

effect
Type: Boolean
A boolean representing whether to animate into position using the position.effect (true), or reposition immediately (false).

Examples

api.reposition(); // Animate into new position
api.reposition(null, false); // Reposition without animation

// Reposition the tooltip when we mouseover specific elements
$('.selector').mouseover(function(event) {
    api.reposition(event); // Pass event object!
});

.focus()

Focuses the tooltip by moving it above all others in the z-index stack. This is the functional equivalent of focusing a window on your desktop, raising it above all others whilst preserving the stacking order.

Signatures

.focus([event])

event
Type: Event
The event object that caused the method call. Ideally passed when the method is called within an event handler.

Examples

api.focus(); // Focus the tooltip manually

// Focus the tooltip when we click specific elements
$('.selector').click(function(event) {
    api.focus(event); // Pass event object!
});

Notes

  • This function triggers a tooltipblur event on the currently focused tooltip (the one highest in the z-index stack).

.blur()

Blurs the tooltip i.e. removes the focus class and triggers the tooltipblur event on the tooltip.

Signatures

.blur([event])

event
Type: Event
The event object that caused the method call. Ideally passed when the method is called within an event handler.

Examples

api.blur(); // Blur the tooltip manually

// Blur the tooltip when we click specific elements
$('.selector').click(function(event) {
    api.blur(event); // Pass event object!
});

.destroy()

Completely removes the tooltip from the page, including all related event handlers and rendered DOM elements, freeing up used memory.

Signatures

.destroy([immediate])

immediate (default: false)
Type: Boolean
A boolean indicating whether or not to call .hide() first, allowing hide effect to be shown before destroying it.

Examples

api.destroy(); // Destroy the tooltip, animating out nicely first
api.destroy(true); // Destroy immediately without hide effect

API Properties

id

Stores the value of the passed id option. If no id was passed, this will be an integer.

rendered

A read-only boolean flag which indicates the current render state of the tooltip i.e. show event has been triggered at least once.

destroyed

A read-only boolean flag which indicates the whether or not the destroy method has been called.

elements

An object containing references to elements relating to the tooltip, including the initial target.

api.elements.target; // Reference to the 'target' element i.e. matched by $('.selector').qtip()
api.elements.tooltip; // Container element for those below
api.elements.titlebar; // Titlebar holds the title (and close button, if enabled) element(s) below
api.elements.title; // Contains the [content.title](./Content#title)
api.elements.button; // Close button defined by [content.button](./Content#button)
api.elements.content; // Contains the [content.text](./Content#text)

Plugins also add additional propeties to this object. Please refer to their individual documentation for details.

timers

An object containing all currently running timers related to show and hide delays.

api.timers = {
    show: timerObject, // Value of the setTimeout call for showing the tooltip (if show.delay is set)
    hide: timerObject // Value of the setTimeout call for hiding the tooltip (if hide.delay is set)
}

options

Object containing all options passed upon initialisation, sanitized and merged with the $.fn.qtip.defaults object. Do not use this object to update a qTip's options! Use the api.set() method instead!

cache

Contains several cached properties and flags that qTip uses internally for various purposes. Great place to store custom flags or values when using the API.

qTip2  - Events

The events object determines the initial event handlers which are bound to the tooltip.

Binding

The API triggers several special events (detailed below) that allow you to bind multiple event handlers to a single qTip and react to certain events. For example, we can bind an event handler that will detect when the tooltip is moved, and update a div element with the tooltip coordinates:

$('.selector').qtip({
    content: 'When I move I update coordinates on the page!',
    events: {
        move: function(event, api) {
            $('#coords').text( event.pageX + '/' + event.pageY );
        }
    }
});

That's great! Simple and easy to integrate. However, what if we need want to not only to update the coordinates, but integrate say, another plugin with the qTip? One that might be in a different file and hard to call within our existing move callback?

$('.selector').qtip({
    content: 'When I move I update coordinates on the page!',
    events: {
        /*
         * Since your qTip will likely have prerender set to false, we'll bind within the render event
         * so we're certain the tooltip is actually rendered before binding our handlers.
         */
        render: function(event, api) {
            // Grab the tooltip element from the API elements object
            var tooltip = api.elements.tooltip;

            // Notice the 'tooltip' prefix of the event name!
            tooltip.bind('tooltipmove', function(event, api) {
                // Update our other plugin and pass our event object
                anotherPlugin.update(event); 
            });

        },
        // Regular old move option still applies
        move: function(event, api) {
            $('#coords').text( event.pageX + '/' + event.pageY );
        }
    }
});

Awesome! Binding multiple events is just as simple, and can be used on all the events listed below. Just make sure to prepend your event name with tooltip when binding events manually.

event.preventDefault()

As is the case with regular events in JavaScript, you can use the event.preventDefault(); to prevent the default event from occurring. For example, within a show event it will stop the tooltip from showing:

$('.selector').qtip({
    content: 'I wont show because one of my show event handlers returns false!',
    show: 'mousedown',
    events: {
        show: function(event, api) {
            event.preventDefault(); // Stop it!
        }
    }
});

This can be handy if you need some conditional logic that determines if the tooltip should show or not. Also be aware that any of the event handlers can stop the default action, not just the first one bound.

event.originalEvent

All of the events below are passed an event object as their first argument. Within this event object is another object called originalEvent. This contains the event that triggered the callback, and can be used for special event detection, such as right-clicks:

$('.selector').qtip({
    content: 'Right-click to open me!',
    show: 'mousedown',
    events: {
        show: function(event, api) {
            // Only show the tooltip if it was a right-click
            if(event.originalEvent.button !== 2) {
                event.preventDefault();
            }
        }
    }
});

events.render

Overview

Fired when the tooltip is rendered

$('.selector').qtip({
    content: {
        text: 'My tooltip content'
    },
    events: {
        render: function(event, api) {
            $('.cartTotal').triggerHandler('update');
        }
    }
});

Examples

Update another element e.g. a cart total, when this tooltip is rendered

See also

Notes

  • The rendering process cannot be interrupted using the event.preventDefault() described above.
  • This event is triggered only once during the lifetime of a single qTip.

events.show

Overview

Fired when the tooltip is shown either by the library itself, or by the user calling the appropriate toggle or show API methods.

Examples

Lets hide another element whenever this tooltip is shown

$('.selector').qtip({
    content: {
        text: 'I hide another element when shown...'
    },
    events: {
        show: function(event, api) {
            $('.hideMe').hide();
        }
    }
});

See also

Notes


events.hide

Overview

Fired when the tooltip is hidden either by the library itself, or by the user calling the appropriate toggle or hide API methods.

Examples

Lets show another element whenever this tooltip is hidden

$('.selector').qtip({
    content: {
        text: 'I cause another element to show when Im hidden...'
    },
    events: {
        hide: function(event, api) {
            $('.showMe').show();
        }
    }
});

See also

Notes


events.toggle

Overview

Fired when the tooltip is toggled i.e. shown or hidden, by the user calling the appropriate toggle or hide API methods. This is a shortcut method for binding to both tooltipshow and tooltiphide events above.

Examples

We can utilise this hide & show shortcut to implement addition/removal of particular properties like classes without duplicating code:

$('.selector').qtip({
    content: {
        text: 'I toggle a class on my target element when shown or hidden!'
    },
    events: {
        toggle: function(event, api) {
            api.elements.target.toggleClass(event.type === 'tooltipshow');
        }
    }
});

See also

Notes

  • There is no tooltiptoggle event! This is a shortcut for binding to both tooltipshow and tooltiphide.
  • Using event.preventDefault() described above, will prevent the tooltip from showing/hiding, depending on the event type being triggered.

events.visible

Overview

Fired when the tooltip becomes visible i.e. immediately after the show.effect has finished and the qTip is visible and has dimensions. This is most useful for plugins and code which requires the tooltip to have layout, that is to be visible and have dimensions, if it is to function correctly.

Because this event is fired after the tooltip is already shown, the event.preventDefault() call will do nothing within this event, since it is already shown when this event is triggered.

Examples

Let's output the dimensions of tooltip once it becomes visible:

$('.selector').qtip({
    content: {
        text: 'I hide another element when shown...'
    },
    events: {
        visible: function(event, api) {
            $('.selector').hide();
        }
    }
});

See also

Notes

  • This is distinct from the show event since it is fired after the show animation is complete, not before.
  • Because of the above, the event.preventDefault() call will do nothing within this event, since it is already shown when this event is triggered

events.hidden

Overview

Fired when the tooltip becomes hidden i.e. immediately after the hide.effect has finished, the qTip is hidden (display:none). This is most useful for plugins and code which requires the tooltip to be completely hidden, if it is to function correctly.

Because this event is fired after the tooltip is already hidden, the event.preventDefault() call will do nothing within this event, since it is already hidden when this event is triggered.

Examples

Let's output the dimensions of tooltip once it becomes hidden:

$('.selector').qtip({
    content: {
        text: 'I show another element when hidden...'
    },
    events: {
        hidden: function(event, api) {
            $('.selector').show();
        }
    }
});

See also

Notse

  • This is distinct from the hide event since it is fired after the hide animation is complete, not before.
  • Because of the above, the event.preventDefault() call will do nothing within this event, since it is already shown when this event is triggered.

events.move

Overview

Fired when the tooltip is repositioned, either by the library itself, or when the user calls the reposition API method.

Examples

Let's update another qTips position, whose position target is actually inside this tooltip.

$('.selector').qtip({
    content: {
        text: 'When I move, I update all qTips who are positioned in relation to me!'
    },
    events: {
        move: function(event, api) {
            // For more information on the API object, check-out the API documentation
            api.elements.content.find('.hasTooltip').qtip('update');
        }
    }
});

See also

Notes


events.focus

Overview

Fired when the tooltip is focused i.e. most recently displayed or moused over, either by the library itself or the focus API method.

Examples

Lets create a qTip whose colour is changed when focused.

$('.selector').qtip({
    content: {
        text: 'When I gain focus over the other qTips, my colour changes!'
    },
    events: {
        focus: function(event, api) {
            // For more information on the API object, check-out the API documentation
            api.elements.tooltip.toggleClass('qtip-blue qtip-cream');
        }
    }
});

See also

Notes


events.blur

Overview

Fired when the tooltip loses focus i.e. another tooltip becomes focused (see above) by the library itself or the focus API method.

Examples

Lets create another qTip whose colour is changed when it loses focus, similar to the example above.
$('.selector').qtip({
    content: {
        text: 'When I lose focus to another qTip, my colour changes!'
    },
    events: {
        blur: function(event, api) {
            // For more information on the API object, check-out the API documentation
            api.elements.tooltip.toggleClass('qtip-blue qtip-cream');
        }
    }
});

See also

Notes

Global properties settings which influence all tooltips on the page

This section covers qTips global options, which effect every qTip created on the page, both past and future.


$.fn.qtip.version

Stores the version of qTip2  library included on the page in the format "2.x.x".


$.fn.qtip.defaults

Holds all the default qTip2  values inherited by your .qtip() calls.

$.fn.qtip.defaults = {
    prerender: false, // Render tooltip HTML on $(document).ready()
    id: false, // Incremental numerical ID used by default
    overwrite: true, // Overwrite previous tooltips on this element
    suppress: true, // Translate 'title' to 'oldtitle' attribute (prevent browser tooltip)
    content: {
        text: true,
        attr: 'title',
        text: false,
        button: false
    },
    position: {
        my: 'top left',
        at: 'bottom right',
        target: false, // Defaults to target element
        container: false, // Defaults to $(document.body)
        viewport: false, // Requires Viewport plugin
        adjust: {
            x: 0, y: 0, // Minor x/y adjustments
            mouse: true, // Follow mouse when using target:'mouse'
            resize: true, // Reposition on resize by default
            method: 'flip flip' // Requires Viewport plugin
        },
        effect: function(api, pos, viewport) {
            $(this).animate(pos, {
                duration: 200,
                queue: false
            });
        }
    },
    show: {
        target: false, // Defaults to target element
        event: 'mouseenter', // Show on mouse over by default
        effect: true, // Use default 90ms fade effect
        delay: 90, // 90ms delay before showing
        solo: false, // Do not hide others when showing
        ready: false, // Do not show immediately
        modal: { // Requires Modal plugin
            on: false, // No modal backdrop by default
            effect: true, // Mimic show effect on backdrop
            blur: true, // Hide tooltip by clicking backdrop
            escape: true // Hide tooltip when Esc pressed
        }
    },
    hide: {
        target: false, // Defaults to target element
        event: 'mouseleave', // Hide on mouse out by default
        effect: true, // Use default 90ms fade effect
        delay: 0, // No hide delay by default
        fixed: false, // Non-hoverable by default
        inactive: false, // Do not hide when inactive
        leave: 'window', // Hide when we leave the window
        distance: false // Don't hide after a set distance
    },
    style: {
        classes: '', // No additional classes added to .qtip element
        widget: false, // Not a jQuery UI widget
        width: false, // No set width
        height: false, // No set height
        tip: { // Requires Tips plugin
            corner: true, // Use position.my by default
            mimic: false, // Don't mimic a particular corner
            width: 8, 
            height: 8,
            border: true, // Detect border from tooltip style
            offset: 0 // Do not apply an offset from corner
        }
    },
    events: {
        render: null, // Called when tooltip rendered
        move: null, // Called when tooltip repositioned
        show: null, // Called when tooltip is about to be shown
        hide: null, // Called when tooltip is about to be hidden
        toggle: null, // Shortcut to binding to two events above
        visible: null, // Called when tooltip is shown
        hidden: null, // Called when tooltip is hidden
        focus: null, // Called when tooltip gains focus
        blur: null // Called when tooltip loses focus
    }
};

Notes

  • Take a look at the Override defaults tutorial for details on how to edit this object properly.

$.fn.qtip.nextid

Overview

Determines the base numeric identifier assigned to future qTips. At document load this is set to zero, and is incremented for each successive qTip created. This identifier is used to retrieve qTips by their corresponding 'id' attr in the form of "qtip-<i>"

Examples

We can start our qTip ID at a higher number, such as 100:

// Set the nextid global option
$.fn.qtip.nextid = 100;

/*
 * This qTip will have an ID of "qtip-100"
 * All qTips created after will have ID values greater than 100
 */
$('.selector').qtip({
    content: {
        text: 'My tooltip content'
    }
});

See also

Notes

  • This MUST be an integer only! If you want to assign a string as an identifier, check-out the individual id option.

$.fn.qtip.inactiveEvents

Value

["click", "dblclick", "mousedown", "mouseup", "mousemove", "mouseleave", "mouseenter"]

Overview

An array of events which, when triggered on the qTip, cause it to become "active" i.e. no longer inactive, and reset the inactive timer assigned to it (if any) by the defined inactive option.

Examples

Let's create a tooltip which hides when it becomes inactive for 3 seconds, inactive in this case meaning when it isn't clicked.

// Set tooltips to only become active when clicked
$.fn.qtip.inactiveEvents = ["click"];

// Create a tooltip that will hide after 3 seconds if it isn't clicked
$('.selector').qtip({
    content: {
        text: 'My tooltip content'
    },
    hide: {
        inactive: 3000
    }
});

See also

Notes

  • This effects all qTips on the page, included those already created (but only if you happen to update a setting which cause the event handlers to be rebound).

$.fn.qtip.zindex

Values

Integer (Default: 15000)

Overview

Determines the base z-index of all qTips on the page of which no qTip z-index will drop below.

Examples

If you're using another plugin that happens to use a higher z-index than the qTip default, increase it a little:

// Now your qTip's appear above the other plugin elements, yipeee!
$.fn.qtip.zindex = 20000;

See also

Notes

  • Updating this option after you've already created some tooltips can have some pretty weird after-effects. Try to avoid it!