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

Documentation

 

Options Reference

Back to the topContent

The content option allows you to specify what appears inside the tooltip. A variety of sub-options are available to you regarding data, simple text strings, HTML, and even dynamically loaded content from other local files. The content option also allows you to specify a title header for your tooltip.
Name Value Description
prerender   As of beta3, this option is false by default! Meaning all tooltips are generated when needed, not at page load.

If set to true, the tooltip will be created on document load, like pre-beta3 releases. 		Setting this to false is useful when your creating tooltips on a large amount of elements at page load: 
content: { prerender: false }
The tooltip will then be created before it is first shown, dramatically reducing page load times.
text   Text/HTML which will appear inside the tooltip initially. If set to false the title attribute of the target element will be used, and if that isn't present, the alt attribute will be used instead.

You can also pass a jQuery DOM array as the argument, which will clone the referenced elements and append them to the tooltip content.

Note: Any content set using this property will be overwritten upon retrieval of remote data e.g. using the url attribute or API updateContent or loadContent methods.		 This will create a default tooltip with the content 'My tooltip content' 
content: { text: 'My tooltip content' }
Dynamic content options. Only needed when retrieving content via AJAX.
url false URL (Uniform Resource Locater) of the content to load. The content must be stored locally as cross-site XMLHTTPRequest is not yet supported by any major browsers.

If set to false, no data retrieval will occur.		 When created, this tooltip will load its content from the local file 'localcontent.html' 
content: { url: 'localcontent.html' }
data null An object containing key/value pairs of all data to be transmitted during the content request to the above URL. The data option is useful if you want to send along identifiers e.g. an articleID, like so: 
content: { url: 'showarticle.php', data: { id: 1 } }
method get A string determining the type of request to use. Possible values are 'get' and 'post'. This option allows you to determine what type of request is used to send the data and retrieve the page. For example, this would result in a GET request: 
content: { url: 'showarticle.php', method: 'get' }
This below example however would result in a POST request, which is useful for sending large amounts of information without including it directly in the URL: 
content: { url: 'showarticle.php', method: 'post' }
title: { Object containing sub-options below
text false Text/HTML which will appear inside the title element of the content.

If set to false, no title element will be created.		 Let's create an About Me tooltip with a title to indicate what the contents are about: 
content: {
   text: 'I really like owls!',
   title: { text: 'About me' }
}
You can also omit the object if your not supplying any other sub-options, like so: 
content: { title: 'About Me' }
button false Text/HTML which will appear inside the title's button element (e.g. close link) located to the right of the title content. Button only appears if title element is created e.g. above title attributes is not false.

If set to false, no button will appear.		 Here's another About Me tooltip, but this time the tooltip stays open until the button, with the text 'Close', is clicked: 
content: {
   text: 'I really like owls!',
   title: {
      text: 'About Me',
      button: 'Close'
   }
},
hide: false

Back to the topPosition

The position option specifies how your tooltip will be positioned in relation to the document. First a target is specified, by default the element which the qTip method was called upon, and placed in relation to it using the corner sub-option. This can then be adjusted using the adjust sub-option's x and y values.
Name Value Description
target false HTML element to position the tooltip in relation to.

Can also be set to position in relation to the mouse.		 You can position the tooltip in relation to any element. Let's position one by the last item of the first unordered list in our document: 
position: { target: $('ul:first li:last') }
We can also position the tooltip in relation to the mouse, so that the tooltip moves with the mouse as long as its on show: 
position: { target: 'mouse' }
You can also specify it as false, which positions it in relation to the element which the qtip method was called upon. This is the default behaviour. 
position: { target: false }
type absolute Positioning type of the tooltip e.g. absolute. In most cases absolute positioning is sufficient. You can use any valid CSS position value in this option including: 
position: { type: 'absolute' }
position: { type: 'fixed' }
The default option is 'absolute' but you can also specify valid non-absolute values: 
position: { type: 'relative' }
position: { type: 'static' }
If you specify 'static', its position will be determined like a regular block element, and position adjustments will no longer work.
container $(document.body) Determines the HTML element which the tooltip is appended to e.g. its container. By specifying the container option you can decide which element your tooltip element will be appended to: 
position: { container: $('div.tooltips') }
This is useful if you want to style tooltips based on CSS selectors.
corner: { Object containing sub-options below
target bottomRight The corner of the target element by which to position the tooltip by. See the positioning tutorial for all possible corner values. Determines the corner of the target element which the tooltip is positioned in relation to. 
position: { corner: { target: 'topMiddle' } }
By omitting the object and supplying simply a string, both the target and tooltip suboption below will be set to the corner, for example: 
position: { corner: 'topMiddle' }
Is equivalent to: 
position: {
   corner: {
      target: 'topMiddle',
      tooltip: 'topMiddle'
   }
}
tooltip topLeft The corner of the tooltip to position in relation to the above targets corner. See the positioning tutorial for all possible corner values. Determines the corner of the tooltip element which is used to position the tooltip. 
position: { corner: { tooltip: 'leftMiddle' } }
adjust: { Object containing sub-options below
x 0 Increment by which to increase the x value of the tooltip coordinate. To decrease, use a minus number. Use this option to specify adjustments to the x coordinate of the final tooltip position. 
position: { adjust: { x: 13, y: 0 } }
y 0 Increment by which to increase the y value of the tooltip coordinate. To decrease, use a minus number. Use this option to specify adjustments to the y coordinate of the final tooltip position. 
position: { adjust: { x: 0, y: 21 } }
mouse true Determines if the tooltips position is adjusted to the mouse position when the position.target is set to 'mouse'. When the position.target is the mouse, this option causes the tooltip position to respond to mouse movement when hovering over the show.target: 
position: {
   target: 'mouse',
   adjust: { mouse: true }
}
Alternatively, you can set it to false, which causes the tooltip to assume the position of the mouse click, but stays static: 
position: {
   target: 'mouse',
   adjust: { mouse: false }
}
This allows you to place the tooltip much like the right-click context menu.
screen false Determines if the tooltips positioning takes into account screen width and height, preventing it from rendering off screen if possible.

Note: Your tip and target corner options may be ignored when adjusting the position.		 Set this option to true to keep the tooltip on-screen at all times, like so: 
position: { adjust: { screen: true } }
When enabled, corner positions and adjustment options may be disregarded to keep the tooltip on-screen.
scroll true Determines if the tooltips position is adjusted when the document is scrolled. Set this option to true to adjust the tooltips position when the document is scrolled: 
position: { adjust: { scroll: true } }
Alternatively, set it to false to prevent its position being updated: 
position: { adjust: { scroll: false } }
resize true Determines if the tooltips position is adjusted when the window is resized. Set this option to true to adjust the tooltips position when the window is resized: 
position: { adjust: { resize: true } }
Alternatively, set it to false to prevent its position being updated: 
position: { adjust: { resize: false } }

Back to the topShow

The show option determines how the tooltip is shown, what effect is used to display it, and when to show it e.g. what event must be triggered.
Name Value Description
delay 140 Time in milliseconds by which to delay the showing of the tooltip. Delay the showing of the tooltip by a set period of milliseconds. If set to zero, no delay will occur: 
show: { delay: 1000 }
solo false Determines whether or not the tooltip will be shown in conjunction with other tooltips or on its own If set to true, all other tooltips will he hidden when this tooltip is shown. 
show: { solo: true }
You may also specify a jQuery DOM array to select specific tooltips which should be hidden, for example: 
show: { solo: $('.qtip-light') }
The above code will hide all tooltips with class name 'qtip-light' before the current tooltip is shown.
ready false Determines whether or not the tooltip is initially hidden or shown when ready If set to true, the tooltip will be shown upon creation: 
show: { ready: true }
If false, it will be initially hidden, which is the default behaviour. 
show: { ready: false }
when: { Object containing sub-options below
target false Defines the HTML element which will assigned the show event handler. The example below will cause the first h1 element to show the tooltip when a mouseover event occurs (default event type): 
show: { when: { target: $('h1:first') } }
When set to false, the tooltip target element will be used e.g. the element the qtip method was called upon. This is the default behaviour. 
show: { when: { target: false } }
event mouseover Event type which will trigger the show event of the tooltip. All possible values are documented under jQuery's Event: bind() documentation. The below example will cause the tooltip to be shown when the target element is clicked: 
show: { when: { event: 'click' } }
All possible values are documented under jQuery's Event: bind() documentation.
effect: { Object containing sub-options below
type fade Effect type to use upon showing the tooltip e.g. fade, slide or grow. Can also be a callback method which will be called when the tooltip is shown. Create a tooltip with the 'slide' type show effect: 
show: { effect: { type: 'slide' } }
The object can omitted if you are not specifying any additional sub-options: 
show: { effect: 'slide' }
You can also specify a callback method, which allows for custom effects to be created. 
show: { effect: myCustomEffect }
The effect length is passed as a parameter to the custom callback to allow for easy referencing.
length 100 Length of time in milliseconds the above effect will last for. This option allows you to set the length of time, in milliseconds, the above effect will occur 
show: { effect: { length: 430 } }

Back to the topHide

The hide option determines how the tooltip is hidden, what effect is used to hide it, and what event must be triggered to hide it.
Name Value Description
delay 0 Time in milliseconds by which to delay the hiding of the tooltip.

When used in conjunction with the fixed hide event, it determines the amount of time the user has to mouseover the tooltip when exiting the target element before the tooltip is hidden.

When used in conjunction with the inactive hide event, it determines how long the tooltip stays visible for before being hidden, when to events are triggered on the tooltip. 		Delay the hiding of the tooltip by a set period of milliseconds. If set to zero, no delay will occur: 
hide: { delay: 1000 }
Allow the user 1000 milliseconds (1 second) to mouseover the tooltip when exiting the target element, before it is hidden: 
hide: { fixed: true, delay: 1000 }
Hide the tooltip after 3000 milliseconds (3 seconds) of inactivity: 
hide: { when: 'inactive', delay: 1000 }
fixed false For use in conjunction with mouseout and similar hide events.

When set to true, the tooltip will not hide if moused over, allowing the contents to be clicked and interacted with. 		When set to true and mouseout or similar events are used, tooltips remain visible when hovered over: 
hide: { when: 'mouseout', fixed: true }
This is useful for creating tooltips with functionality e.g. edit/delete links for articles etc.
when: { Object containing sub-options below
target false Defines the HTML element which will assigned the hide event handler. The example below will cause the first h1 element to hide the tooltip when a mouseover event occurs (default event type): 
hide: { when: { target: $('h1:first') } }
When set to false, the tooltip target element will be used e.g. the element the qtip method was called upon. This is the default behaviour. 
hide: { when: { target: false } }
event mouseover Event type which will trigger the hide event of the tooltip. There are two custom events available: 'inactive' and 'unfocus'.

The 'unfocus' event hides the tooltip when anywhere else on the document, except the tooltip itself, is clicked. The 'inactive' event hies the tooltip after a set period of inactivity, which is determined by the hide.delay option.

All other possible values are documented under jQuery's Event: bind() documentation.		 The below example will cause the tooltip to be hidden when the target element is clicked: 
hide: { when: { event: 'click' } }
This one will hide the tooltip when anywhere else except the tooltip is clicked: 
hide: { when: { event: 'unfocus' } }
And this will hide the tooltip after 2 seconds of inactivity: 
hide: { when: { event: 'inactive' }, delay: 2000 }
You can also omit the when object and simply declare a string, if your not declaring a target: 
hide: { when: 'inactive', delay: 2000 }
effect: { Object containing sub-options below
type fade Effect type to use upon hiding the tooltip e.g. fade, slide or grow. Can also be a callback method which will be called when the tooltip is hidden. Create a tooltip with the 'slide' type hide effect: 
hide: { effect: { type: 'slide' } }
The object can omitted if you are not specifying any additional sub-options: 
hide: { effect: 'slide' }
You can also specify a callback method, which allows for custom effects to be created. 
hide: { effect: myCustomEffect }
The effect length is passed as a parameter to the custom callback to allow for easy referencing.
length 100 Length of time in milliseconds the above effect will last for. This option allows you to set the length of time, in milliseconds, the above effect will occur 
show: { effect: { length: 430 } }

Back to the topStyle

The style option allows you to set how your tooltip styled, including many sub-options such as width, border and element classes. Each tooltip is styled according to the passed style option, allowing you to customize each tooltip separately.
Name Value Description
name   Name of the tooltip style to apply to the generated tooltip. Use this option to choose what tooltip style to apply to your tooltip. qTip comes with 5 preset styles: cream, light, dark, green and red. 
style: { name: 'dark' }
Any properties that are not explicitly set in your style object will inherit values from the style you chose above. You can also create custom styles to be inherited from, which is documented here. To use a custom style, simply declare its name as the name value: 
style: { name: 'mystyle' }
CSS-Attribute   Any valid CSS attribute/value pair can be specified here.

Note: Make sure to surround attribute names in quotation marks to avoid problems! 		You can declare any CSS attribute and value pair here: 
style: { title: { 'color': 'red', 'overflow': 'hidden' } }
Be sure to surround all your attribute names in quotation marks, as many of them contain hyphens, which are not valid charaters for object names in JavaScript! For example: 
style: { title: { 'font-size': 12 } } // Valid
style: { title: { font-size: 12 } } // NOT valid!
See the jQuery CSS section for more details.
width: { Either a number OR an object containing sub-options below
min 0 Determines the minimum width of the tooltip. Determines the minimum width of the tooltip in pixels: 
style: { width: { min: 75 } }
If the width of the tooltip is lower than this set value at any point, it will be set to the defined value.
max 250 Determines the maximum width of the tooltip. Determines the maximum width of the tooltip in pixels: 
style: { width: { max: 250 } }
If the width of the tooltip exceeds this set value at any point, it will be set to the defined value.
border: { Object containing sub-options below
width 3 Determines the border width of the tooltip. Determines the width of the tooltips border in pixels 
style: { border: { width: 5 } }
You can omit the object if you are not specifying any other sub-options like so: 
style: { border: 5 }
radius 0 Determines the border radius, or roundness, of the tooltip border. Determines the radius of the tooltips border in pixels. 
style: { border: { radius: 5 } }
It's recommended you also specify a width to prevent rendering bugs: 
style: { border: { width: 2, radius: 5 } }
color #d3d3d3 Determines the colour of the tooltip border Determines the colour of the tooltips border. 
style: { border: { color: 'black' } }
Any valid CSS color value can be used as the option value.
tip: { Object containing sub-options below
corner topLeft The corner of the tooltip the tip will be placed in relation to. See the positioning tutorial for all possible corner strings. Determines the corner of the tooltip on which the tip will be displayed 
style: { tip: { corner: 'rightBottom' } }
See the tips tutorial for all possible corner strings.
color false Determines the colour of the tooltips tip. If set to false, the border colour will be used Determines the colour of the tooltips tip. 
style: { border: { color: '#D1E6BB' } }
Any valid CSS color value can be used as the option value.
size {x:12,y:12} An object containing x and y coordinates, or width and height, of the tip. This option allows you to set the height and width of the tip via x and y coordinates 
style: { tip: { size: { x: 12, y: 18 } } }
Note: Depending on the corner which the tip is located, the x and y values could relate to either the width or the height! So watch out.
title: { Object containing sub-options below
CSS-Attribute   Any valid CSS attribute/value pair can be specified here.

Note: Make sure to surround attribute names in quotation marks to avoid problems! 		You can declare any CSS attribute and value pair here: 
style: { title: { 'color': 'red', 'overflow': 'hidden' } }
Be sure to surround all your attribute names in quotation marks, as many of them contain hyphens, which are not valid charaters for object names in JavaScript! For example: 
style: { title: { 'font-size': 12 } } // Valid
style: { title: { font-size: 12 } } // NOT valid!
See the jQuery CSS section for more details.
button: { Object containing sub-options below
CSS-Attribute   Any valid CSS attribute/value pair can be specified here.

Note: Make sure to surround attribute names in quotation marks to avoid problems! 		You can declare any CSS attribute and value pair here: 
style: { button: { 'color': 'red', 'font-weight': 'bold' } }
Be sure to surround all your attribute names in quotation marks, as many of them contain hyphens, which are not valid charaters for object names in JavaScript! For example: 
style: { button: { 'font-size': 12 } } // Valid
style: { title: { font-size: 12 } } // NOT valid!
See the jQuery CSS section for more details.
classes: { Object containing sub-options below
target   Class name assigned to the target element e.g. the element defined by the target option  
tooltip qtip Class name assigned to the tooltip.  
tip qtip-tip Class name assigned to the tooltip tip.  
title qtip-title Class name assigned to the tooltip title.  
content qtip-content Class name assigned to the tooltip content.  
active qtip-active Class name assigned to any tooltip which is currently active e.g. on show.  

Back to the topAPI

The API option is simply a subset of the API Callbacks object. See here for full details and documentation.

Name Value Description
api: { Object containing sub-options below
Callback   See here for full details on all valid API callbacks for this object.