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'
    }
};

// Example 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.

.get()

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

Signatures

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

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

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

.hide()

Helper method for calling .toggle(false).

Signatures

.disable()

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

Signatures

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

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

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

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

Examples

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

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.