QuickNav

Options

content
disabled
hide
items
position
show
tooltipClass
track

Methods

close
destroy
disable
enable
open
option
widget

Events

create
open
close

Tooltip Widgetversion added: 1.9

Description: Customizable, themeable tooltips, replacing native tooltips.

Options

contentType: Function() or String

Default: function returning the title attribute

The content of the tooltip.

When changing this option, you likely need to also change the items option.

Multiple types supported:
  • Function: A callback which can either return the content directly, or call the first argument, passing in the content, e.g., for Ajax content.
  • String: A string of HTML to use for the tooltip content.

disabledType: Boolean

Default: false
Disables the tooltip if set to true.

hideType: Boolean or Number or String or Object

Default: null
If and how to animate the hiding of the tooltip.
Multiple types supported:
  • Boolean: When set to false, no animation will be used and the tooltip will be hidden immediately. When set to true, the tooltip will fade out with the default duration and the default easing.
  • Number: The tooltip will fade out with the specified duration and the default easing.
  • String: The tooltip will be hidden using the specified effect. The value can either be the name of a built-in jQuery animateion method, such as "slideUp", or the name of a jQuery UI effect, such as "fold". In either case the effect will be used with the default duration and the default easing.
  • Object: If the value is an object, then effect, duration, and easing properties may be provided. If the effect property contains the name of a jQuery method, then that method will be used; otherwise it is assumed to be the name of a jQuery UI effect. When using a jQuery UI effect that supports additional settings, you may include those settings in the object and they will be passed to the effect. If duration or easing is omitted, then the default values will be used. If effect is omitted, then "fadeOut" will be used.

itemsType: Selector

Default: [title]

A selector indicating which items should show tooltips. Customize if you're using something other then the title attribute for the tooltip content, or if you need a different selector for event delegation.

When changing this option, you likely need to also change the content option.

positionType: Object

Default: { my: "left+15 center", at: "right center", collision: "flipfit" }
Configuration for the Position utility. The of property defaults to the target element, but can also be overriden.

showType: Boolean or Number or String or Object

Default: null
If and how to animate the showing of the tooltip.
Multiple types supported:
  • Boolean: When set to false, no animation will be used and the tooltip will be shown immediately. When set to true, the tooltip will fade in with the default duration and the default easing.
  • Number: The tooltip will fade in with the specified duration and the default easing.
  • String: The tooltip will be shown using the specified effect. The value can either be the name of a built-in jQuery animateion method, such as "slideDown", or the name of a jQuery UI effect, such as "fold". In either case the effect will be used with the default duration and the default easing.
  • Object: If the value is an object, then effect, duration, and easing properties may be provided. If the effect property contains the name of a jQuery method, then that method will be used; otherwise it is assumed to be the name of a jQuery UI effect. When using a jQuery UI effect that supports additional settings, you may include those settings in the object and they will be passed to the effect. If duration or easing is omitted, then the default values will be used. If effect is omitted, then "fadeIn" will be used.

tooltipClassType: String

Default: null
A class to add to the widget, can be used to display various tooltip types, like warnings or errors.

This may get replaced by the classes option.

trackType: Boolean

Default: false
Whether the tooltip should track (follow) the mouse.

Methods

close( [event ] )

Closes a tooltip. If the widget's element is the target, the event argument is optional. Otherwise you have to pass an event object with the currentTarget property pointing at the target.
  • event
    Type: Event
    What triggered the tooltip to close.

destroy()

Removes the tooltip functionality completely. This will return the element back to its pre-init state.

disable()

Disables the tooltip.

enable()

Enables the tooltip.

open( [event ] )

Programmatically open a tooltip. If the widget's element is the target, the event argument is optional. Otherwise you have to pass an event object with the currentTarget property pointing at the target.
  • event
    Type: Event
    What triggered the tooltip to open.

option( optionName ) Returns: Object

Gets the value currently associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to get.

option() Returns: PlainObject

Gets an object containing key/value pairs representing the current tooltip options hash.

option( optionName, value )

Sets the value of the tooltip option associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to set.
  • value
    Type: Object
    A value to set for the option.

option( options )

Sets one or more options for the tooltip.
  • options
    Type: Object
    A map of option-value pairs to set.

widget() Returns: jQuery

Returns a jQuery object containing the original element.

Events

close( event, ui )

Triggered when a tooltip is closed, triggered on focusout or mouseleave.
  • event
    Type: Event
  • ui
    Type: Object
    • tooltip
      Type: jQuery
      The generated tooltip element.

create( event, ui )

Triggered when the tooltip is created.

open( event, ui )

Triggered when a tooltip is shown, triggered on focusin or mouseover.
  • event
    Type: Event
  • ui
    Type: Object
    • tooltip
      Type: jQuery
      The generated tooltip element.

Tooltip replaces native tooltips, making them themable as well as allowing various customizations:

  • Display other content than just the title, like inline footnotes or extra content retrieved via Ajax.
  • Customize the positioning, e.g., to center the tooltip above elements.
  • Add extra styling to customize the appearance, for warning or error fields.

A fade animation is used by default to show and hide the tooltip, making the appearance a bit more organic, compared to just toggling the visiblity. This can be customized with the show and hide options.

The items and content options need to stay in-sync. If you change one of them, you need to change the other.

Additional Notes:

  • This widget requires some functional CSS, otherwise it won't work. If you build a custom theme, use the widget's specific CSS file as a starting point.

Examples:

Example: Create a tooltip on the document, using event delegation for all elements with a title attribute.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>tooltip demo</title>
    <link rel="stylesheet" href="http://code.jquery.com/ui/1.9.0/themes/base/jquery-ui.css">
    <script src="http://code.jquery.com/jquery-1.8.2.js"></script>
    <script src="http://code.jquery.com/ui/1.9.0/jquery-ui.js"></script>
</head>
<body>
 
<p>
    <a href="#" title="Anchor description">Anchor text</a>
    <input title="Input help">
</p>
<script>
    $( document ).tooltip();
</script>
 
</body>
</html>

Demo:

Example: Create a tooltip on the paragraph element, matching all images with an alt attribute. Use the alt attribute as the tooltip's content for each image.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>tooltip demo</title>
    <link rel="stylesheet" href="http://code.jquery.com/ui/1.9.0/themes/base/jquery-ui.css">
    <script src="http://code.jquery.com/jquery-1.8.2.js"></script>
    <script src="http://code.jquery.com/ui/1.9.0/jquery-ui.js"></script>
</head>
<body>
 
<p>
    <img src="/resources/images/st-stephens.jpg" alt="St. Stephen's Cathedral">
    <img src="/resources/images/tower-bridge.jpg" alt="Tower Bridge">
</p>
 
<script>
$( "p" ).tooltip({
    items: "img[alt]",
    content: function() {
        return $( this ).attr( "alt" );
    }
});
</script>
 
</body>
</html>

Demo: