jQuery UI tooltip documentation

## 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.

Code examples:

Initialize the tooltip with the content option specified:

`$(` `".selector"` `).tooltip({ content:` `"Awesome title!"` `});`

Get or set the content option, after initialization:

`// getter` `var` `content = $(` `".selector"` `).tooltip(` `"option"``,` `"content"` `);` `// setter` `$(` `".selector"` `).tooltip(` `"option"``,` `"content"``,` `"Awesome title!"` `);`

### disabledType: Boolean

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

Initialize the tooltip with the disabled option specified:

`$(` `".selector"` `).tooltip({ disabled:` `true` `});`

Get or set the disabled option, after initialization:

`// getter` `var` `disabled = $(` `".selector"` `).tooltip(` `"option"``,` `"disabled"` `);` `// setter` `$(` `".selector"` `).tooltip(` `"option"``,` `"disabled"``,` `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.

Code examples:

Initialize the tooltip with the hide option specified:

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

Get or set the hide option, after initialization:

`// getter` `var` `hide = $(` `".selector"` `).tooltip(` `"option"``,` `"hide"` `);` `// setter` `$(` `".selector"` `).tooltip(` `"option"``,` `"hide"``, { effect:` `"explode"``, duration: 1000 } );`

### 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.

Code examples:

Initialize the tooltip with the items option specified:

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

Get or set the items option, after initialization:

`// getter` `var` `items = $(` `".selector"` `).tooltip(` `"option"``,` `"items"` `);` `// setter` `$(` `".selector"` `).tooltip(` `"option"``,` `"items"``,` `"img[alt]"` `);`

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

Initialize the tooltip with the position option specified:

`$(` `".selector"` `).tooltip({ position: { my:` `"center top"``, at:` `"center bottom+5"` `} });`

Get or set the position option, after initialization:

`// getter` `var` `position = $(` `".selector"` `).tooltip(` `"option"``,` `"position"` `);` `// setter` `$(` `".selector"` `).tooltip(` `"option"``,` `"position"``, { my:` `"center top"``, at:` `"center bottom+5"` `} );`

### 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.

Code examples:

Initialize the tooltip with the show option specified:

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

Get or set the show option, after initialization:

`// getter` `var` `show = $(` `".selector"` `).tooltip(` `"option"``,` `"show"` `);` `// setter` `$(` `".selector"` `).tooltip(` `"option"``,` `"show"``, { effect:` `"blind"``, duration: 800 } );`

### 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.

Code examples:

Initialize the tooltip with the tooltipClass option specified:

`$(` `".selector"` `).tooltip({ tooltipClass:` `"custom-tooltip-styling"` `});`

Get or set the tooltipClass option, after initialization:

`// getter` `var` `tooltipClass = $(` `".selector"` `).tooltip(` `"option"``,` `"tooltipClass"` `);` `// setter` `$(` `".selector"` `).tooltip(` `"option"``,` `"tooltipClass"``,` `"custom-tooltip-styling"` `);`

### trackType: Boolean

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

Initialize the tooltip with the track option specified:

`$(` `".selector"` `).tooltip({ track:` `true` `});`

Get or set the track option, after initialization:

`// getter` `var` `track = $(` `".selector"` `).tooltip(` `"option"``,` `"track"` `);` `// setter` `$(` `".selector"` `).tooltip(` `"option"``,` `"track"``,` `true` `);`

## Methods

### close()

Closes a tooltip. This is only intended to be called for non-delegated tooltips.

- This method does not accept any arguments.

### destroy()

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

- This method does not accept any arguments.

### disable()

Disables the tooltip.

- This method does not accept any arguments.

### enable()

Enables the tooltip.

- This method does not accept any arguments.

### open()

Programmatically open a tooltip. This is only intended to be called for non-delegated tooltips.

- This method does not accept any arguments.

### 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.

- This method does not accept any arguments.

### 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.

- This method does not accept any arguments.

## 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.

- event
  Type: Event
- ui
  Type: Object

### 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.1/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.1/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.1/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.1/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: