qTip 1.0 will soon be obsolete... check-out the qTip2 preview here!

API Reference

Back to the topShortcut methods

Before we delve into the full API capabilities, it's worth nothing that there are a select few API methods available to you without accessing the API directly. These methods are destroy, disable and enable, and can be called by supplying their names as strings as arguments within the qtip() call on either the tooltip and/or its target.

$(mytooltip).qtip("show"); // Shows the tooltip
$(mytooltip).qtip("hide"); // Hides the tooltip
$(mytooltip).qtip("focus"); // Focuses the tooltip
$(mytooltip).qtip("disable"); // Disables the tooltip
$(mytooltip).qtip("enable"); // Enables the tooltip
$(mytooltip).qtip("destroy"); // Destroys the tooltip

Note: these are simply shortcuts to the actual API methods, which are documented in detail below.

Back to the topAccessing the API

Access to a tooltips full API capabilities is provided through the use of the api argument of the qtip() method and as above, can be accessed via both the target and the tooltip, like so:

var api = $(mytooltip).qtip("api"); // Access the API via the tooltip
var alternate_api = $(mytooltiptarget).qtip("api"); // Access the API via the tooltips target

Obviously replace mytooltip and mytooltiptarget with your jQuery selectors or DOM element references. Once you have access to the API above, you can fully utilise all available methods and attributes documented below.

Back to the topMethods

qTip's API provides you with several methods to interact with and manipulate the chosen tooltips attributes and features.
Name Arguments Description
show event Call this method to show the tooltip with the options provided when the tooltip was created.

Access to this function is also available through the shortcut qtip("show") argument.
hide event Call this method to hide the tooltip with the options provided when the tooltip was created.

Access to this function is also available through the shortcut qtip("hide") argument.
focus event Calling this method causes the tooltip to be 'focused' e.g. moved above all others in the tooltip stack. This adjusts the z-index of all other tooltips when called.

Access to this function is also available through the shortcut qtip("focus") argument.
disable state When called with state set to true, the tooltip will be temporarily disabled, and will not fire any events e.g. hide, show, focus. If called with state set to false, the tooltip will be enabled and will fire all assigned events.

Access to this function is also available through the shortcut qtip("enable") and qtip("disable") arguments.
updateWidth width When called this method updates the width of the tooltip relative to contents within it. It is avised you call this method when updating the tooltip contents directly without using the updateContent API method.

If a width is supplied, the tooltip width is set to the supplied value.
updatePosition event, animate When called this method updates the position of the tooltip using the options provided when the tooltip was created.

If animate is set to true, a smooth transition will occur to the new position, otherwise the position is set immediately.
getPosition Returns the current position of the tooltip relative to the document e.g. [0,0] is the top left corner of the viewport/document.
getDimensions Returns the current dimensions (i.e. height and width) of the tooltip, regardless of its current display state.
updateStyle name When called this method updates the style of the tooltip to the specified style 'name'. This can be either a preset (e.g. red, blue) or custom global style, but must be defined prior to calling this method.

Note: For details on defining custom global styles, see the Styling tutorial.
updateContent content, reposition Updates the tooltips HTML content to the provided content string. The tooltip position is also updated once the new content is set. If reposition is set to false the tooltips position on-screen and its tip position will not be updated.

If images are contained within the content, tooltip position will be updated once all images are loaded to prevent mis-positioning.
loadContent url, data, method Updates the tooltips content with that of the file url, which is passed optional an data array with the defined request method e.g. GET or POST.

Note: This method utilises the above updateContent method to update the tooltip contents and as such, fires the associated beforeContentUpdate and onContentUpdate events.
updateTitle content Updates the tooltip titles HTML content to the provided content string. Button elements, if enabled, are preserved.
destroy Destroys the tooltip and removes all bound associated events. Access to this function is also available through the shortcut qtip("destroy") argument.

Back to the topCallbacks

Also available are event driven callback methods, allowing you to extend qTip's functionality via third party scripts.
Name Parameters Description
beforeRender   Called before the tooltip is rendered.

If content.prerender is to set to true, this method will be called on document load, on each tooltip, as it is rendered. If set to false, which is the default behaviour, this method will be called when the tooltip is first shown e.g. when its first show event is triggered.

Note: When using this method, it is important to note that nothing but the API options and target element can be accessed within the function scope, since the tooltip has not yet been rendered.
onRender   Called after the tooltip is rendered.
beforePositionUpdate event Called before the tooltip position is updated.

Note: If false is returned by the callback, the tooltip position will not be updated.
onPositionUpdate event Called after the tooltip position is updated.
beforeShow event Called before the tooltip is shown.

Note: If false is returned by the callback, the tooltip will not be shown.
onShow event Called after the tooltip is shown.
beforeHide event Called before the tooltip is hidden.

Note: If false is returned by the callback, the tooltip will not be hidden.
onHide event Called after the tooltip is hidden.
beforeFocus event Called before the tooltip is focused, either by the user, or when a tooltip is moused over.

Note: If false is returned by the callback, the tooltip will not be focused.
onFocus event Called after the tooltip is focused, either by the user, or when a tooltip is moused over.
beforeContentUpdate event, content Called before the tooltip content is updated by the updateContent or loadContent methods, or when the url option is provided in the options.

Note: If the return value of the callback is a string, the string will be used as the content.
Note: If false is returned by the callback, the tooltip content will not be updated.
onContentUpdate event Called after the tooltip content is updated by the updateContent or loadContent methods, or when the url option is provided within the options.
beforeContentLoad   Called before the tooltip content is updated by the loadContent method or when url option is provided.

Note: If false is returned by the callback, the tooltip content will not be updated.
onContentLoad   Called after the tooltip content is updated by the loadContent method or when the url option is provided within the options.
beforeTitleUpdate Called before the tooltips title content is updated by the updateTitle method.

Note: If false is returned by the callback, the tooltips title content will not be updated.
onTitleUpdate Called after the tooltips title content is updated by the updateTitle method.
beforeDestroy   Called before the tooltip is destroyed. If false is returned by the callback, the destroy will be halted.
onDestroy   Called after the tooltip is destroyed.

Back to the topAttributes

The API provides you with references to all major DOM elements of the tooltip as well as the options provided to create the tooltip.
Name Description
options References the option object which was provided when the qtip() method was first called.
elements: { Object containing sub-options below
target A jQuery DOM object referencing the target element of the tooltip.
tooltip A jQuery DOM object referencing the tooltip element.
tip A jQuery DOM object referencing the tip element of the tooltip.
wrapper A jQuery DOM object referencing the wrapper element of the tooltip. This encapsulates all elements except the tip.
contentWrapper A jQuery DOM object referencing the content wrapper element of the tooltip. This encapsulates both the content and title elements.
title A jQuery DOM object referencing the title element of the tooltip. As of beta4 this is placed outside the content element.
button A jQuery DOM object referencing the button element of the tooltip. This element is only available when the title is displayed and buttons are enabled.
content A jQuery DOM object referencing the content element of the tooltip.
For full details on the core HTML structure of the tooltip see the HTML Structure section.