Shorthand options Make life easier with shorthand mappings
Examples
qTip2 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 } }
Core top-level configuration options
The core options are the options which have no parent object i.e. they are all located in the upper configuration object, as detailed below.
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
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 what is going inside your tooltip? And how?
The content object defines what content will be displayed within the tooltip, as well as the the title of the tooltip and various other aspects.
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.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.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.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.
Position configure where your tooltips show on-screen
The position object defines various attributes of the tooltip position, including the element it is positioned in relation to, and when the position is adjusted within defined viewports.
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.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
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.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
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.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.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.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.adjust.method
Overview
Determines the type of viewport positioning used. See the plugin documentation for more information.
Show choose how and when your tooltips appear
The show object defines what events trigger the tooltip to show on which elements, as well as the initial delay and several other properties.
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
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
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
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
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
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.
Hide choose how and when your tooltips disappear from view
The hide object defines what events trigger the tooltip to hide on which elements, as well as the initial delay and several other properties.
Special events
qTip2 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
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
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
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
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
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
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
Notes
- By default a fadeOut animation takes place with a duration of 90ms.
Style tweak the appearance of your tooltips
The style object allows you to assign custom classes to the main qTip element, as well as Themeroller and tip options when using the tips plugin
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.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.
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
- 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
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
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
- 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
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
Notes
- The blurring process cannot be prevented using the event.preventDefault() described above.
Global options 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.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!