Examples

qTip² supports multiple shorthand notations, which allow you to write certain options in a more compact manor. For example, these two are equivalent:

$('.selector').qtip({
    content: 'My content'
});

$('.selector').qtip({
    content: {
        text: 'My content'
    }
});

As you can see, this allows you to remove the need for the additional object syntax, but means you cannot set any of the other content options. Bare this in mind when using this notation!

Complete list

On the left is the shorthand notation, and on the right what it maps to in full notation.

// Core
metadata: value, // metadata: { type: value }

// Content
content: value, // content: { text: value }
content: { title: value }, // content: { title: { text: value } }
content: { ajax: 'string' }, // content: { ajax: { url: 'string' } }

// Positioning
position: 'string', // position: { my: 'string', at: 'string' }

// Hide and show
show: true, // show: { ready: true }
show: 'string', // show: { event: 'string' }
hide: 'string', // hide: { event: 'string' }
show: $('.selector'), // show: { target: $('.selector') }
hide: $('.selector'), // hide: { target: $('.selector') }

// Styles
style: 'string', // style: { classes: 'string' }
style: { tip: value }, // style: { tip: { corner: value } }
show: { modal: value }, // show: { modal: { on: value } }

id

Values

"String", false (Default: false)

Overview

A unique string that determines the value of the qTip's "id" attribute that can be used to easily identify this qTip in the document.The attribute is prepended with 'qtip-'.

Examples

This tooltip will be assigned an "id" value of "qtip-myTooltip"

$('.selector').qtip({
    id: 'myTooltip',
    content: {
        text: 'My ID is #qtip-myTooltip'
    }
});

It can then be easily found in the document via simple jQuery selectors like so:

$('#qtip-myTooltip');

Notes

• By default, this is a unique positive integer.
• Value must be unique and contain no special characters.
• If a qTip is already present with this ID, the ID will be discarded and a numeric ID used instead.

prerender

Values

true, false (Default: false)

Overview

By default, tooltips are rendered when they are first triggered, rather than on page load. Setting this to true will cause tooltips to be created on page load, which can have significant page load increases if a large set of elements are being targeted.

Examples

Create a simple tooltip and create it on page load

$('.selector').qtip({
    prerender: true,
    content: {
        text: 'My simple tooltip'
    }
});

See also

• show.ready

Notes

• Setting this to true can cause dramatic increases in page load times.

overwrite

Values

true, false (Default: true)

Overview

Determines if, when the .qtip() method is called on an element with a qTip already present, the new one overrides (i.e. destroys) the old one. By default this is true i.e. calling .qtip() on an element will always destroy any previous bound qTips by default.

Examples

Create a tooltip that will not override (destroy) the previous qTip, but fail silently:

/* First tooltip, grabs its content from the title attribute */
$('.selector').qtip();

/*
 * Second qTip   - this won't do anything, as we've 
 * instructed it not to overwrite any prior qTip elements.
 */
$('.selector').qtip({
    overwrite: false,
    content: {
        text: 'You won\'t see me... boo!'
    }
});

Notes

• This option is set to false when using the live event delegation option

suppress

Values

true, false (Default: true)

Overview

Determines whether or not the default browser tooltips are suppressed for the selectors elements when the qTip is created. The suppression is accomplished by renaming the 'title' attribute of the elements(s) to 'oldtitle'.

The jQuery .attr() method is overloaded to allow you to grab the title without modifying your current code, by returning 'oldtitle' when requesting the 'title' attribute on elements with qTips present and suppression enabled.

The jQuery .clone() method is also overloaded to return cloned elements, with qTips present, with their regular title attributes intact. If however, you clone the element(s) passing true as the first parameter (thereby cloning not only the element but also any data on it), the 'oldtitle' attribute will remain, and will not be returned to its original 'title' attribute.

Examples

Create a qTip that is shown on click, but doesn't suppress the regular browser tooltip, allowing it to be used as an indicator:

$('.selector').qtip({
    suppress: false,
    content: {
        text: 'You must have known to click me from the browser tooltip...!?'
    },
    show: {
        event: 'click'
    }
})
.attr('title', 'Click me to show a qTip!'); // Apply a title attribute to the elements

Notes

• This option is most useful when creating tooltips that don't trigger on mouseover/out

metadata

Overview

If you happen to use the jQuery Metadata plugin on your web page, you can utilise it to supply options for your tooltips on a per-element basis. This option object determines the metadata plugins options when called by qTip.

Examples

Let's setup some elements with custom metadata attached via a custom tag:

<div qtipOpts="{ style: { classes: 'qtip-blue' } }">*Hover me* to see a blue tooltip</div>
<div qtipOpts="{ show: { event: 'click' } }">*Click me* to show a regular tooltip</div>

Now let's attach some tooltips and search for options within the qtipOpts attribute:

$('div[qtipOpts]').qtip({
    metadata: {
        type: 'attr',
        name: 'qtipOpts'
    },
    content: 'I might look different from all the other tooltips generated by the same .qtip() call...'
});

You can also utilise the new HTML5 data-* attributes in a similar way by setting up your data like so:

// Elements with data-qtipopts defined as a valid options object will automatically have it merged into the .qtip() calls options.
<div data-qtipopts="{ style: { classes: 'qtip-green' } }">*Hover me* to see a green tooltip</div>

...and then specifying 'html5' as you metadata type, along with the data attributes name (the bit after the hyphen):

$('div[qtipOpts]').qtip({
    metadata: {
        type: 'html5', // Use HTML5 data-* attributes
        name: 'qtipopts' // Grab the metadata from the data-qtipOpts HTML5 attribute
    },
    content: 'I\'m using HTML5 to set my style... so so trendy.'
});

Notes

• HTML5 data: Make sure not to use data-qtip are your storage location, as it will interfere with qTip as of jQuery 1.4.3! See here for why.
• For more information on other metadata options, checkout the Metadata Documentation.

content.text

Values

Deferred, function(){}, jQuery([ ]), "String", true (Default: true)

Overview

Content which will appear inside the tooltip initially. If set to true the title attribute of the target will be used, if available.

You can also specify a function that returns the content, which will be run on each consecutive show event. This function can return both static textual content (text or HTML), or a Deferred object (see below) The function is executed with its scope as the target element, along with both an event and api argument(s) respectively.

Deferred content

A Deferred object may be used as the value, with both progress() and done() handlers causing the content to be set. The content will not be set upon rejection.

Examples

This will create a default tooltip with the content 'My tooltip content'

$('.selector').qtip({
    content: {
        text: 'My tooltip content'
    }
});

We can also use another jQuery element as the tooltip content:

$('.selector').qtip({
    content: {
        text: $('.selector2') // Add .clone() if you don't want the matched elements to be removed, but simply copied
    }
});

We can also use a custom function to retrieve special attributes from the target element on each show event:

$('.selector').qtip({
    content: {
        text: function(event, api) {
            // Retrieve content from custom attribute of the $('.selector') elements.
            return $(this).attr('qtip-content');
        }
    }
});

Finally, we can utilise the above with jQuery's Deferred objects to grab content via an .ajax() call:

$('.selector').qtip({
    content: {
        text: function(event, api) {
            $.ajax({ url: 'custom/content.html' })
                .done(function(html) {
                    api.set('content.text', html)
                })
                .fail(function(xhr, status, error) {
                    api.set('content.text', status + ': ' + error)
                })

            return 'Loading...';
        }
    }
});

Notes

• If no valid content can be detected in both this and the below content.attr option, no tooltip will be rendered.
• Custom functions that return no valid content will still cause the tooltip to be created! Replace these with an each() loop if this is not the desired behaviour.

See also

• content.title

content.attr

Values

"String" (Default: "title")

Overview

Attribute of the target element to use for content if none is provided with the above content.text option, or no valid content can be found.

Examples

Let's create qTip's on all images whose content is provided by the elements ALT attribute

$('img[alt]').qtip({
    content: {
        attr: 'alt'
    }
});

This is useful for image galleries and other image-oriented sites that need to provide nice visual cues of their context.

Notes

• If no valid content is found within the elements attribute, and content.text is not defined, no tooltip will be rendered.

See also

• content.text

content.title

Values

Deferred, function(){}, jQuery([ ]), "String", true (Default: true)

Overview

Content which will appear inside the tooltip initially. If set to true the title attribute of the target will be used, if available.

You can also specify an function that returns the content, which will be run on each consecutive show event. This function can return both static textual content (text or HTML), or a Deferred object (see below) The function is executed with its scope as the target element, along with both an event and api argument(s) respectively.

Deferred content

A Deferred object may be used as the value, with both progress() and done() handlers causing the content to be set. The content will not be set upon rejection.

Examples

Create an "About me" tooltip with a title to indicate what the contents are about:

$('.selector').qtip({
    content: {
        text: 'I really like owls!',
        title: 'About me'
    }
});

We can also use another jQuery element as the tooltip title:

$('.selector').qtip({
    content: {
        title: $('.selector2') // Add .clone() if you don't want the matched elements to be removed, but simply copied
    }
});

We can also use a custom function to return the title text:

$('.selector').qtip({
    content: {
        text: 'Custom title text functions... hoorah!',
        title: function(event, api) {
            // Retrieve content from ALT attribute of the $('.selector') element
            return $(this).attr('alt');
        }
    }
});

Finally, we can utilise the above with jQuery's Deferred objects to grab content via an .ajax() call:

$('.selector').qtip({
    content: {
        text: 'AJAX calll... but just for the title content!',
        title: function(event, api) {
            $.ajax({ url: 'custom/content.html' })
                .done(function(html) {
                    api.set('content.title', html)
                })
                .fail(function(xhr, status, error) {
                    api.set('content.title', status + ': ' + error)
                })

            return 'Loading...';
        }
    }
});

Notes

• Prior to qTip 2.1, this option was known as content.title.text, which is still supported but deprecated.
• If no valid content is provided, the title will not be created.

See Also

• content.text

content.button

Values

jQuery([ ]), "String", true, false (Default: false)

Overview

Text/HTML which will appear inside the button element (i.e. close button or link) located by default at the top right of the tooltip or titlebar (if enabled). The button will close the tooltip when clicked.

If it is set to true the default styled icon will be used. If a jQuery element is provided it will be used as the button and appended to the tooltip, or titlebar element (if enabled). Finally, if a string is provided it will be used as the buttons innerText and title/aria-title attributes.

Examples

Create another "About me" tooltip which opens on click and only hides when the title button is clicked

$('.selector').qtip({
    content: {
        text: 'Quite Fancybox-y if you ask me...',
        button: true
    },
    hide: {
        event: false
    }
});

You can also have tooltips with a title, in which case the button will lye within it:

$('.selector').qtip({
    content: {
        text: 'I really like owls!',
        title: 'I have a button to my right!',
        button: 'Close'
    },
    hide: {
        event: false
    }
});

Notes

• Prior to qTip 2.1, this option was known as content.title.button, which is still supported but deprecated
• Button will be appended to the titlebar element if content.title is set, otherwise to the tooltip element.
• If no valid content is provided, the button will not be created.

content.ajax

Overview

Deprecated as of qTip 2.1. Please use jQuery Deferred Objects as your content.text instead. A full explanation is available in the Content Guide.

Basics

qTip utilises a special positioning system using corners. The basic concept behind it is pretty simple, in fact it turns out to be plain English when read aloud! For example, let's say we want to position my tooltips top left corner at the bottom right of my target. Simple enough... let's see the code involved in this:

$('.selector').qtip({
    content: 'I am positioned using corner values!',
    position: {
        my: 'top left',  // Position my top left...
        at: 'bottom right', // at the bottom right of...
        target: $('.selector') // my target
    }
});

Notice how reading down the object you begin to see a logical plain English pattern emerge. Much easier than using x and y coordinates! Here's a diagram of all valid corner values for use with position.my and position.at options as well as the tips plugin corner and mimic options.

Notes

• This system is heavily based upon the jQuery UI Position plugin

position.target

Values

jQuery([ ]), [x, y], "mouse", "event", false (Default: false)

Overview

HTML element the tooltip will be positioned in relation to. Can also be set to 'mouse' or the 'event' (position at target that triggered the tooltip), or an array containing an absolute x/y position on the page.

If you also have position.adjust.mouse set to true, the qTip will follow the mouse until a hide event is triggered on the hide.target

Examples

Let's position our tooltip in relation to the last LI element of the first UL element in our document:

$('.selector').qtip({
    content: {
        text: 'I am positioned in relation to a different element'
    },
    position: {
        target: $('ul:first li:last')
    }
});

We can also position the tooltip in relation to the mouse, so that the tooltip is given the x/y coordinates of the mouse on show

$('.selector').qtip({
    content: {
        text: 'I am positioned in relation to the mouse'
    },
    position: {
        target: 'mouse'
    }
});

It's also possible to position the same tooltip in relation to multiple targets using several hide/show targets. This is handy for situations where you need to use similar tooltips for several elements on the page.

$('.selector').qtip({
    content: {
        text: 'I position to whatever show target triggered me.'
    },
    position: {
        target: 'event'
    },
    show: {
        target: $('.selector, .selectorTwo')
    },
    hide: {
        target: $('.selector, .selectorTwo')
    }
});

And last but not least, absolute positioning via an x/y array e.g. a tooltip at 10px from left and top of the page:

$('.selector').qtip({
    content: {
        text: 'I am absolutely positioned, but still work with the viewport property!'
    },
    position: {
        target: [10, 10]
    }
});

Notes

• Setting this to false causes the tooltip is positioned in relation to the element .qtip() was called upon.
• When using absolute positioning ([x, y]) the Viewport plugin adjustment still works as expected.

See also

• position.viewport

position.my

Values

"Corner", false (Default: "top left")

Overview

The corner of the tooltip to position in relation to the position.at. See the Basics section for all possible corner values.

Examples

Let's create a tooltip that's positioned to the left center of our target:

$('.selector').qtip({
    content: {
        text: 'My center left corner is positioned next to my target'
    },
    position: {
        my: 'left center'
    }
});

Notes

• See the Basics section for all possible corner values.

See Also

• position.at
• position.target

position.at

Values

"Corner", false (Default: "bottom right")

Overview

The corner of the position.target element to position the tooltips corner at. See the Basics section for all possible corner values.

Examples

Let's create a tooltip thats positioned to the top left of our target:

$('.selector').qtip({
    content: {
        text: 'I am positioned as the top left of my target'
    },
    position: {
        at: 'top left'
    }
});

Notes

• See the Basics section for all possible corner values.

See Also

• position.at
• position.target

position.container

Values

jQuery([ ]), false (Default: document.body)

Overview

Determines the HTML element which the tooltip is appended to e.g. its containing element.

Examples

Let's append our tooltip to a custom 'tooltips' container:

$('.selector').qtip({
    content: {
        text: 'I am appended within a custom tooltips DIV'
    },
    position: {
        container: $('div.tooltips')
    }
});

Notes

• By default all tooltips are appended to the document.body element
• If the containing element has overflow set to anything other than "visible" this will confine the qTip's visibility to the containers boundaries.

position.viewport

Overview

Allows the tooltip to adjust its position to keep within a set viewport element. See the plugin documentation for more information.

position.effect

Values

Function, false (Default: see below)

Overview

Determines the type of effect that takes place when animating a tooltips position. A custom method can also be used, which is passed the new position as one of its parameters, and whose scope is the tooltip element.

The default animation callback is:

function(api, pos) {
    $(this).animate(pos, { duration: 200, queue: FALSE });
}

Examples

Let's create a tooltip that slides into its position on screen with linear easing

$('.selector').qtip({
    content: {
        text: 'When my position is updated I slide into place. Nifty huh?'
    },
    position: {
        effect: function(api, pos, viewport) {
            // "this" refers to the tooltip
            $(this).animate(pos, {
                duration: 600,
                easing: 'linear',
                queue: false // Set this to false so it doesn't interfere with the show/hide animations
            });
        }
    }
});

We can also disable the default slide animation by passing false:

$('.selector').qtip({
    content: {
        text: 'I don\'t slide like the rest of them...'
    },
    position: {
        effect: false
    }
});

Notes

• By default a custom, slide animation takes place using the custom function listed above.
• The use of the animation "queue" option eliminates the problem of hiding/showing tips whilst repositioning. This could have other side-effects, so enable if you run into problems

position.adjust.x

Values

Integer (Default: 0)

Overview

A positive or negative pixel value by which to offset the tooltip in the horizontal plane e.g. the x-axis. Negative values cause a reduction in the value e.g. moves tooltip to the left.

Examples

Let's fine tune our tooltips position by offsetting it 10 pixels to the right:

$('.selector').qtip({
    content: {
        text: 'My position is adjusted by 10px on the horizontal'
    },
    position: {
        adjust: {
            x: 10
        }
    }
});

Notes

• Currently this option only supports pixel values. All other unit values are ignored

See also

• position.adjust.y

position.adjust.y

Values

Integer (Default: 0)

Overview

A positive or negative pixel value by which to offset the tooltip in the vertical plane e.g. the y-axis. Negative values cause a reduction in the value e.g. moves tooltip upwards.

Examples

Let's fine tune our tooltips position by offsetting it 12 pixels upwards:

$('.selector').qtip({
    content: {
        text: 'My position is adjusted by -12px on the vertical'
    },
    position: {
        adjust: {
            y: -12
        }
    }
});

Notes

• Currently this option only supports pixel values. All other unit values are ignored

See also

• position.adjust.x

position.adjust.mouse

Values

true, false (Default: true)

Overview

When the position.target is set to mouse, this option determines whether the tooltip follows the mouse when hovering over the show.target.

Examples

Let's make a tooltip which follows our mouse when visible

$('.selector').qtip({
    content: {
        text: 'I follow the mouse whilst I am visible. Weeeeee!'
    },
    position: {
        target: 'mouse',
        adjust: {
            mouse: true  // Can be omitted (e.g. default behaviour)
        }
    }
});

Alternatively, we can set it to false and make the tooltip assume the position of the mouse when shown, but not follow it, similar to how a right-click or "context" menu is positioned.

$('.selector').qtip({
    content: {
        text: 'I am positioned under the mouse when first visible, but I stay here... very boring!'
    },
    position: {
        target: 'mouse',
        adjust: {
            mouse: false
        }
    }
});

Notes

• Only applies when the position.target is set to mouse

See also

• position.target

position.adjust.resize

Values

true, false (Default: true)

Overview

Determines if the tooltips position is adjusted when the window is resized.

Examples

Set this option to true to adjust the tooltips position when the window is resized:

$('.selector').qtip({
    content: {
        text: 'If you resize your window while I am visible, I will adjust my position accordingly.'
    },
    position: {
        target: $(document),
        adjust: {
            resize: true // Can be ommited (e.g. default behaviour)
        }
    }
});

Alternatively, set it to false to prevent its position being updated:

$('.selector').qtip({
    content: {
        text: 'Sadly... I don\'t respond to window resize :('
    },
    position: {
        target: $(document),
        adjust: {
            resize: false
        }
    }
});

See also

• position.target

position.adjust.scroll

Values

true, false (Default: true)

Overview

Determines if the tooltips position is adjusted when the window (or position.container) is scrolled.

Examples

Set this option to true to adjust the tooltips position when the window (or position.container) is scrolled:

$('.selector').qtip({
    content: {
        text: 'If you scroll your window while I am visible, I will auto-adjust my position.'
    },
    position: {
        target: $(document),
        adjust: {
            scroll: true // Can be ommited (e.g. default behaviour)
        }
    }
});

Alternatively, set it to false to prevent its position being updated:

$('.selector').qtip({
    content: {
        text: 'Sadly... I don\'t respond to window scroll :('
    },
    position: {
        target: $(document),
        adjust: {
            scroll: false
        }
    }
});

See also

• position.target

position.adjust.method

Overview

Determines the type of viewport positioning used. See the plugin documentation for more information.

show.target

Values

jQuery([]), false (Default: false)

Overview

Defines the HTML element(s) which will trigger your specified (show.event(s))(#event). When set to false, the element the .qtip() method was called upon is used.

Examples

This example will cause the first H1 element to show the tooltip when the show.event is triggered (in this case mouseenter):

$('.selector').qtip({
    content: {
        text: 'You moused over the first H1 element on the document.'
    },
    show: {
        target: $('h1:first')
    }
});

We can also cause the tooltip to open if multiple elements are moused over e.g. all header elements:

$('.selector').qtip({
    content: {
        text: 'You moused over a header element'
    },
    show: {
        target: $('h1, h2, h3, h4')
    }
});

See also

• show.event

Notes

• Setting a different show target does not effect the positioning, which is controlled via the position.target option.

show.event

Values

"String", false (Default: "mouseenter")

Overview

Event(s) which will trigger the tooltip to be shown. All possible values are documented under jQuery's (Event bind())(http://docs.jquery.com/Events/bind#typedatafn) documentation. Multiple, space separated events are supported.

Examples

The below example will cause the tooltip to be shown when the target element is clicked:

$('.selector').qtip({
    content: {
        text: 'I get shown on click'
    },
    show: {
        event: 'click'
    }
});

You can also specify multiple events using a space separated string. This example will make your tooltips appear when the show.target is clicked or a mouseover occurs:

$('.selector').qtip({
    content: {
        text: 'I get shown on click'
    },
    show: {
        event: 'click mouseenter'
    }
});

See also

• show.target

Notes

• mouseenter is the non-bubbling version of mouseover, and is the preferred event to use.

show.delay

Values

Integer (Default: 90)

Overview

Time in milliseconds by which to delay showing of the tooltip when the show.event is triggered on the show.target

Examples

This tooltip will only show after hovering the show.target for 1000ms (1 second):

$('.selector').qtip({
    content: {
        text: 'I have a longer delay then default qTips'
    },
    show: {
        delay: 1000
    }
});

See also

• show.target

Notes

• This works much like the hoverIntent plugin by Brian Cherne.*
• This property can cause problems on iOS devices such as the iPad and iPhone. See here for a full discussion.

show.solo

Values

jQuery([]), String, true, false (Default: false)

Overview

Determines whether or not the tooltip will hide all others when the show.event is triggered on the show.target. If a jQuery object is used as its value, only tooltips found within that object will be hidden. If a string is passed, it used as a jQuery selector to select all tooltips to be hidden.

Examples

Let's create a simple tooltip that hides all others when shown

$('.selector').qtip({
    content: {
        text: 'You won\' see me with any other tooltips... I\'m too cool for that!'
    },
    show: {
        solo: true
    }
});

Or if for some reason we want to hide only a sub-set of the tooltips, we can define a parent common to them

$('.selector').qtip({
    content: {
        text: 'I hide other tooltips when I\'m shown... booya!'
    },
    show: {
        solo: $('.qtips') // Hide tooltips within the .qtips element when shown
    }
});

See also

• show.target

Notes

• In RC3 it was possible to specify which tooltips which should be hidden. This feature is slightly different in 2.0, allowing to specify only a common parent to those tooltips instead.

show.ready

Values

true, false (Default: false)

Overview

Determines whether or not the tooltip is shown as soon as it is bound to the element i.e. when the .qtip() call is fired. This is useful for tooltips which are created inside event handlers, as without it they won't show up immediately.

Examples

Create a tooltip that's shown on document load. This could be handy for things like step-by-step tutorials.

$('.selector').qtip({
    content: {
        text: 'I\'m visible on page load'
    },
    show: {
        ready: true
    }
});

See also

• prerender
• document.ready()

Notes

• This option obeys your show.delay setting, so set it to zero if you want it to show instantly on page load!
• Enabling this option on multiple tooltips which are bound on document.ready or window.load, can slow down your page load times.

show.effect

Values

function(){}, true, false (Default: true)

Overview

Determines the type of effect that takes place when showing the tooltip. A custom method can also be used whose scope is the tooltip element when called. If set to false, no animation takes place.

Examples

Let's create a tooltip that slides down when shown using a custom animation callback:

$('.selector').qtip({
    content: {
        text: 'I slide in when shown, none of this fading business for me!'
    },
    show: {
        effect: function(offset) {
            $(this).slideDown(100); // "this" refers to the tooltip
        }
    }
});

See also

• hide.effect

Notes

• By default a fadeIn animation takes place with a duration of 90ms.

show.modal

Overview

Defines the tooltip's modal properties. See the plugin documentation for more information.

Special events

qTip²  implements some custom hide and show events for you so you don't have to code the manually. At the moment there's only one: unfocus. This event allows you to hide the tooltip when anything other then the tooltip is clicked.

$('.selector').qtip({
    content: {
        text: 'I\'ll hide when you click anywhere else on the document'
    },
    hide: {
        event: 'unfocus'
    }
});

Note: This is a qTip only event, it will not work with any normal jQuery bind/live/delegate calls.

hide.target

Values

jQuery([]), false (Default: false)

Overview

Defines the HTML element(s) which will trigger your specified hide.event. When set to false, the element the .qtip() method was called upon is used.

Examples

This example will cause the first H1 element to hide the tooltip when the hide.event is triggered (in this case mouseleave):

$('.selector').qtip({
    content: {
        text: 'You hovered over the first H1 element on the document. Well done you!'
    },
    hide: {
        target: $('h1:first')
    }
});

We can also cause the tooltip to close if multiple elements are moused over e.g. all header elements:

$('.selector').qtip({
    content: {
        text: 'If you mouse over a header element, I\'ll hide!'
    },
    show: {
        ready: true
    },
    hide: {
        target: $('h1, h2, h3, h4')
    }
});

See also

• hide.event

Notes

• Setting a different hide target does not effect the positioning, which is controlled via the position.target option.

hide.event

Values

"String", false (Default: "mouseleave")

Overview

Event(s) which will trigger the tooltip to be hidden. All possible values are documented under jQuery's Event bind() documentation. Multiple, space separated events are supported.

Examples

The below example will cause the tooltip to be hidden when the target element is clicked:

$('.selector').qtip({
    content: {
        text: 'I get hidden on click'
    },
    hide: {
        event: 'click'
    }
});

You can also specify multiple events using a space separated string. This example will make your tooltips appear when the hide.target is clicked or a mouseout occurs:

$('.selector').qtip({
    content: {
        text: 'I get hidden on click or when you mouseout my hide.target'
    },
    hide: {
        event: 'click mouseleave'
    }
});

See also

• hide.target

Notes

• mouseleave is the non-bubbling version of mouseout, and is the preferred event to use.

hide.delay

Values

Integer (Default: 0)

Overview

Time in milliseconds by which to delay hiding of the tooltip when the hide.event is triggered on the hide.target

Examples

This tooltip will only hide after hovering the hide.target for 1000ms (1 second):

$('.selector').qtip({
    content: {
        text: 'I have a longer delay then default qTips'
    },
    hide: {
        delay: 1000
    }
});

hide.inactive

Values

Integer, false (Default: false)

Overview

Time in milliseconds in which the tooltip should be hidden if it remains inactive e.g. isn't interacted with. If set to false, tooltip will not hide when inactive.

Examples

Let's create a tooltip that shows on click, but hides only when inactive for 3 seconds:

$('.selector').qtip({
    content: {
        text: 'I\'ll disappear after three seconds of inactivity... :(',
    },
    show: 'click',
    hide: {
        event: false,
        inactive: 3000
    }
});

See also

• inactiveEvents
• hide.event

Notes

• Inactivity is judged by the absense of any of the defined inactive events, which are a global property.
• In 1.0 the inactive event was applied via the hide.event option and used the hide.delay to define the duration of inactivity needed.

hide.fixed

Values

true, false (Default: false)

Overview

When set to true, the tooltip will not hide if moused over, allowing the contents to be clicked and interacted with.

Examples

Create a tooltip with a link inside that can be moused over without hiding:

$('.selector').qtip({
    content: {
        text: $['(Visit Google](http://google.com)'),
    },
    hide: {
        fixed: true
    }
});

See also

• hide.event

Notes

• Adding a hide delay is generally done when this is enabled to give the user time to mouseover the tooltip before hiding
• Primarily for use in conjunction with mouseout and similar mouse-orientated hide events.

hide.leave

Values

"window", false (Default: "window")

Overview

Additional hide setting that allows you to specify whether the tooltip will hide when leaving the window it's contained within. This option requires you to be using either mouseout or mouseleave as (one of) your hide events.

Examples

This tooltip will not hide when you mouse out of the window e.g. tab to another window/tab or click a link that opens a new window.

$('.selector').qtip({
    content: {
        text: 'I will not hide when you click the link I target (.selector)',
    },
    hide: {
        leave: false
    }
});

See also

• hide.event

Notes

• This only applies when using mouseout or mouseleave as (one of) your hide event(s)

hide.distance

Values

Integer, false (Default: false)

Overview

This setting allows you to determine the distance after which the tooltip hides when the mouse is moved from the point it triggered the tooltip. This is what the regular browser tooltips behave like.

Examples

Let's mimic the regular browser tooltips by using the distance option and mouse settings:

$('.selector').qtip({
    content: {
        text: 'I behave exactly like a regular browser tooltip',
    },
    position: {
        target: 'mouse', // Position at the mouse...
        adjust: { mouse: false } // ...but don't follow it!
    }
    hide: {
        distance: 15 // Hide it after we move 15 pixels away from the origin
    }
});

See also

• hide.event
• show.target
• position.target

Notes

• The event itself is classed as a hide option, but the initial position of the mouse on the show.target is what determines the coordinates used to calculate the distance.

hide.effect

Values

Function, true, false (Default: true)

Overview

Determines the type of effect that takes place when hiding the tooltip. A custom method can also be used whose scope is the tooltip element when called. If set to false, no animation takes place.

Examples

Let's create a tooltip that slides down when hidden using a custom animation callback:

$('.selector').qtip({
    content: {
        text: 'I slide in when hidden, none of this fading business for me!'
    }
    hide: {
        effect: function(offset) {
            $(this).slideDown(100); // "this" refers to the tooltip
        }
    }
});

See also

• show.effect

Notes

• By default a fadeOut animation takes place with a duration of 90ms.

style.classes

Values

"String", false (Default: "")

Overview

A space separated string containing all class names which should be added to the main qTip element. There are several base styles included in the CSS file provided, including:

/* CSS2 styles */
qtip{ } /* This one is applied by default (formally the "cream" style) */
qtip-plain{ }
qtip-light{ }
qtip-dark{ }
qtip-red{ }
qtip-green{ }
qtip-blue{ }

/* CSS3+ styles */
qtip-shadow{ } /* Adds a shadows to your tooltips */
qtip-rounded{ } /* Adds a rounded corner to your tooltips */
qtip-bootstrap{ } /* Bootstrap style */
qtip-tipsy{ } /* Tipsy style */
qtip-youtube{ } /* Youtube style */
qtip-jtools{ } /* jTools tooltip style */
qtip-cluetip{ } /* ClueTip style */
qtip-tipped{ } /* Tipped style */

Examples

Create a tooltip with the included blue theme and a shadow:

$('.selector').qtip({
    content: {
        text: 'I\'m blue... deal with it!'
    },
    style: {
        classes: 'qtip-blue qtip-shadow'
    }
});

style.def

Values

true, false (Default: true)

Overview

This property allows you to prevent the .qtip-default class from being applied to the main tooltip element.

Notes

• Setting this to false will cause the tooltip to have no visual styling if you haven't applied any custom classes

style.widget

Values

true, false (Default: false)

Overview

Determines whether or not the ui-widget classes of the Themeroller UI styles are applied to your tooltip

Notes

• For more information on Themeroller classes checkout their documentation

See also

• style.classes

style.width

Values

"String", Integer, false (Default: false)

Overview

This property allows you to override all applied CSS width styles for the tooltip. Can be any valid width CSS value. Please note that this does not override max/min width styles! Change those in the CSS file provided.

Notes

• Again, this does not override max/min width styles!

style.height

Values

"String", Integer, false (Default: false)

Overview

This propery allows you to override all applied CSS height styles for the tooltip. Can be any valid width CSS value. Please note that this does not override max/min height styles! Change those in the CSS file provided.

Notes

• Again, this does not override max/min height styles!

style.tip

Overview

Defines the tooltip's tip properties. See the plugin documentation for more information.

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

• prerender
• show.ready

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

• Show options

Notes

• Using event.preventDefault() described above, will prevent the tooltip from showing.

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

• Hide options

Notes

• Using event.preventDefault() described above, will prevent the tooltip from hiding.

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

• Show options
• Hide options

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

• Show event
• Show options

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

• Hide event
• Hide options

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

• Position options

Notes

• Using event.preventDefault() described above, will prevent the tooltips position from being updated.

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

• Blur event

Notes

• Using event.preventDefault() described above, will prevent the tooltip from becoming focused.

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

• Focus event

Notes

• The blurring process cannot be prevented using the event.preventDefault() described above.

$.fn.qtip.version

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

$.fn.qtip.defaults

Holds all the default qTip²  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

• id option

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

• hide.inactive

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

• modal.zindex

Notes

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