API A full reference of the libraries inner workings

The API features extensive methods and attributes for interacting with the inner workings of qTip2 ! Especially useful when in use with other 3rd party plugins.

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.

API Methods A full reference of API methods

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

.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 A full reference of API properties

The API features a helpful amount of properties for use with the API Methods.

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.