Tooltip Widget

Categories: Widgets

Tooltip Widgetversion added: 1.9

Description: Customizable, themeable tooltips, replacing native tooltips.

QuickNavExamples

Options

Methods

Events

Tooltip replaces native tooltips, making them themeable 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 visibility. 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.

In general, disabled elements do not trigger any DOM events. Therefore, it is not possible to properly control tooltips for disabled elements, since we need to listen to events to determine when to show and hide the tooltip. As a result, jQuery UI does not guarantee any level of support for tooltips attached to disabled elements. Unfortunately, this means that if you require tooltips on disabled elements, you may end up with a mixture of native tooltips and jQuery UI tooltips.

Keyboard interaction

When the tooltip is open and the corresponding item has focus, the following key commands are available:

  • ESCAPE: Close the tooltip.

Theming

The tooltip widget uses the jQuery UI CSS framework to style its look and feel. If tooltip specific styling is needed, the following CSS class names can be used:

  • ui-tooltip: The outer container for the tooltip.
    • ui-tooltip-content: The content of the tooltip.

Dependencies

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.

Options

content 

Type: 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.
Code examples:

Initialize the tooltip with the content option specified:

1
2
3
 
$( ".selector" ).tooltip({
  content: "Awesome title!"
});

Get or set the content option, after initialization:

1
2
3
4
5
 
// Getter
var content = $( ".selector" ).tooltip( "option", "content" );
 
// Setter
$( ".selector" ).tooltip( "option", "content", "Awesome title!" );

disabled 

Type: Boolean
Default: false
Disables the tooltip if set to true.
Code examples:

Initialize the tooltip with the disabled option specified:

1
2
3
 
$( ".selector" ).tooltip({
  disabled: true
});

Get or set the disabled option, after initialization:

1
2
3
4
5
 
// Getter
var disabled = $( ".selector" ).tooltip( "option", "disabled" );
 
// Setter
$( ".selector" ).tooltip( "option", "disabled", true );

hide 

Type: Boolean or Number or String or Object
Default: true
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 animation 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, delay, 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. If delay is omitted, then no delay is used.
Code examples:

Initialize the tooltip with the hide option specified:

1
2
3
 
$( ".selector" ).tooltip({
  hide: { effect: "explode", duration: 1000 }
});

Get or set the hide option, after initialization:

1
2
3
4
5
 
// Getter
var hide = $( ".selector" ).tooltip( "option", "hide" );
 
// Setter
$( ".selector" ).tooltip( "option", "hide", { effect: "explode", duration: 1000 } );

items 

Type: Selector
Default: [title]

A selector indicating which items should show tooltips. Customize if you're using something other than 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.

Code examples:

Initialize the tooltip with the items option specified:

1
2
3
 
$( ".selector" ).tooltip({
  items: "img[alt]"
});

Get or set the items option, after initialization:

1
2
3
4
5
 
// Getter
var items = $( ".selector" ).tooltip( "option", "items" );
 
// Setter
$( ".selector" ).tooltip( "option", "items", "img[alt]" );

position 

Type: Object
Default: { my: "left top+15", at: "left bottom", collision: "flipfit" }

Identifies the position of the tooltip in relation to the associated target element. The of option defaults to the target element, but you can specify another element to position against. You can refer to the jQuery UI Position utility for more details about the various options.

Code examples:

Initialize the tooltip with the position option specified:

1
2
3
 
$( ".selector" ).tooltip({
  position: { my: "left+15 center", at: "right center" }
});

Get or set the position option, after initialization:

1
2
3
4
5
 
// Getter
var position = $( ".selector" ).tooltip( "option", "position" );
 
// Setter
$( ".selector" ).tooltip( "option", "position", { my: "left+15 center", at: "right center" } );

show 

Type: Boolean or Number or String or Object
Default: true
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 animation 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, delay, 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. If delay is omitted, then no delay is used.
Code examples:

Initialize the tooltip with the show option specified:

1
2
3
 
$( ".selector" ).tooltip({
  show: { effect: "blind", duration: 800 }
});

Get or set the show option, after initialization:

1
2
3
4
5
 
// Getter
var show = $( ".selector" ).tooltip( "option", "show" );
 
// Setter
$( ".selector" ).tooltip( "option", "show", { effect: "blind", duration: 800 } );

tooltipClass 

Type: 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.

Code examples:

Initialize the tooltip with the tooltipClass option specified:

1
2
3
 
$( ".selector" ).tooltip({
  tooltipClass: "custom-tooltip-styling"
});

Get or set the tooltipClass option, after initialization:

1
2
3
4
5
 
// Getter
var tooltipClass = $( ".selector" ).tooltip( "option", "tooltipClass" );
 
// Setter
$( ".selector" ).tooltip( "option", "tooltipClass", "custom-tooltip-styling" );

track 

Type: Boolean
Default: false
Whether the tooltip should track (follow) the mouse.
Code examples:

Initialize the tooltip with the track option specified:

1
2
3
 
$( ".selector" ).tooltip({
  track: true
});

Get or set the track option, after initialization:

1
2
3
4
5
 
// Getter
var track = $( ".selector" ).tooltip( "option", "track" );
 
// Setter
$( ".selector" ).tooltip( "option", "track", true );

Methods

close()Returns: jQuery (plugin only)

Closes a tooltip. This is only intended to be called for non-delegated tooltips.
  • This method does not accept any arguments.
Code examples:

Invoke the close method:

1
 
$( ".selector" ).tooltip( "close" );

destroy()Returns: jQuery (plugin only)

Removes the tooltip functionality completely. This will return the element back to its pre-init state.
  • This method does not accept any arguments.
Code examples:

Invoke the destroy method:

1
 
$( ".selector" ).tooltip( "destroy" );

disable()Returns: jQuery (plugin only)

Disables the tooltip.
  • This method does not accept any arguments.
Code examples:

Invoke the disable method:

1
 
$( ".selector" ).tooltip( "disable" );

enable()Returns: jQuery (plugin only)

Enables the tooltip.
  • This method does not accept any arguments.
Code examples:

Invoke the enable method:

1
 
$( ".selector" ).tooltip( "enable" );

instance()Returns: Object

Retrieves the tooltip's instance object. If the element does not have an associated instance, undefined is returned.

Unlike other widget methods, instance() is safe to call on any element after the tooltip plugin has loaded.

  • This method does not accept any arguments.
Code examples:

Invoke the instance method:

1
 
$( ".selector" ).tooltip( "instance" );

open()Returns: jQuery (plugin only)

Programmatically open a tooltip. This is only intended to be called for non-delegated tooltips.
  • This method does not accept any arguments.
Code examples:

Invoke the open method:

1
 
$( ".selector" ).tooltip( "open" );

option( optionName )Returns: Object

Gets the value currently associated with the specified optionName.

Note: For options that have objects as their value, you can get the value of a specific key by using dot notation. For example, "foo.bar" would get the value of the bar property on the foo option.

  • optionName
    Type: String
    The name of the option to get.
Code examples:

Invoke the method:

1
 
var isDisabled = $( ".selector" ).tooltip( "option", "disabled" );

option()Returns: PlainObject

Gets an object containing key/value pairs representing the current tooltip options hash.
  • This signature does not accept any arguments.
Code examples:

Invoke the method:

1
 
var options = $( ".selector" ).tooltip( "option" );

option( optionName, value )Returns: jQuery (plugin only)

Sets the value of the tooltip option associated with the specified optionName.

Note: For options that have objects as their value, you can set the value of just one property by using dot notation for optionName. For example, "foo.bar" would update only the bar property of the foo option.

  • optionName
    Type: String
    The name of the option to set.
  • value
    Type: Object
    A value to set for the option.
Code examples:

Invoke the method:

1
 
$( ".selector" ).tooltip( "option", "disabled", true );

option( options )Returns: jQuery (plugin only)

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

Invoke the method:

1
 
$( ".selector" ).tooltip( "option", { disabled: true } );

widget()Returns: jQuery

Returns a jQuery object containing the original element.
  • This method does not accept any arguments.
Code examples:

Invoke the widget method:

1
 
var widget = $( ".selector" ).tooltip( "widget" );

Events

close( event, ui )Type: tooltipclose

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

Initialize the tooltip with the close callback specified:

1
2
3
 
$( ".selector" ).tooltip({
  close: function( event, ui ) {}
});

Bind an event listener to the tooltipclose event:

1
 
$( ".selector" ).on( "tooltipclose", function( event, ui ) {} );

create( event, ui )Type: tooltipcreate

Triggered when the tooltip is created.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the tooltip with the create callback specified:

1
2
3
 
$( ".selector" ).tooltip({
  create: function( event, ui ) {}
});

Bind an event listener to the tooltipcreate event:

1
 
$( ".selector" ).on( "tooltipcreate", function( event, ui ) {} );

open( event, ui )Type: tooltipopen

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

Initialize the tooltip with the open callback specified:

1
2
3
 
$( ".selector" ).tooltip({
  open: function( event, ui ) {}
});

Bind an event listener to the tooltipopen event:

1
 
$( ".selector" ).on( "tooltipopen", function( event, ui ) {} );

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="//code.jquery.com/ui/1.11.4/themes/smoothness/jquery-ui.css">
  <script src="//code.jquery.com/jquery-1.10.2.js"></script>
  <script src="//code.jquery.com/ui/1.11.4/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: