Tooltip Widget version added: 1.9
Description: Customizable, themeable tooltips, replacing native tooltips.
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.
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.
Dependencies
- UI Core
- Widget Factory
- Position
- Effects Core (optional; for use with the
show
andhide
options)
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
contentType: Function() or String
function returning the title attribute
The content of the tooltip.
When changing this option, you likely need to also change the items
option.
- 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.
Initialize the tooltip with the content option specified:
1 |
|
Get or set the content option, after initialization:
1 2 3 4 5 |
|
disabledType: Boolean
false
true
.Initialize the tooltip with the disabled option specified:
1
|
|
Get or set the disabled option, after initialization:
1
2
3
4
5
|
|
hideType: Boolean or Number or String or Object
null
- Boolean: When set to
false
, no animation will be used and the tooltip will be hidden immediately. When set totrue
, 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
, andeasing
properties may be provided. If theeffect
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. Ifduration
oreasing
is omitted, then the default values will be used. Ifeffect
is omitted, then"fadeOut"
will be used. Ifdelay
is omitted, then no delay is used.
Initialize the tooltip with the hide option specified:
1 |
|
Get or set the hide option, after initialization:
1 2 3 4 5 |
|
itemsType: Selector
[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.
Initialize the tooltip with the items option specified:
1
|
|
Get or set the items option, after initialization:
1
2
3
4
5
|
|
positionType: Object
{ 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.
Initialize the tooltip with the position option specified:
1
|
|
Get or set the position option, after initialization:
1
2
3
4
5
|
|
showType: Boolean or Number or String or Object
null
- Boolean: When set to
false
, no animation will be used and the tooltip will be shown immediately. When set totrue
, 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
, andeasing
properties may be provided. If theeffect
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. Ifduration
oreasing
is omitted, then the default values will be used. Ifeffect
is omitted, then"fadeIn"
will be used. Ifdelay
is omitted, then no delay is used.
Initialize the tooltip with the show option specified:
1 |
|
Get or set the show option, after initialization:
1 2 3 4 5 |
|
tooltipClassType: String
null
This may get replaced by the classes option.
Initialize the tooltip with the tooltipClass option specified:
1
|
|
Get or set the tooltipClass option, after initialization:
1
2
3
4
5
|
|
trackType: Boolean
false
Initialize the tooltip with the track option specified:
1
|
|
Get or set the track option, after initialization:
1
2
3
4
5
|
|
Methods
close()
-
This method does not accept any arguments.
Invoke the close method:
1
|
|
destroy()
-
This method does not accept any arguments.
Invoke the destroy method:
1
|
|
disable()
-
This method does not accept any arguments.
Invoke the disable method:
1
|
|
enable()
-
This method does not accept any arguments.
Invoke the enable method:
1
|
|
open()
-
This method does not accept any arguments.
Invoke the open method:
1
|
|
option( optionName )Returns: Object
optionName
.-
optionNameType: StringThe name of the option to get.
Invoke the method:
1
|
|
option()Returns: PlainObject
-
This method does not accept any arguments.
Invoke the method:
1
|
|
option( optionName, value )
optionName
.-
optionNameType: StringThe name of the option to set.
-
valueType: ObjectA value to set for the option.
Invoke the method:
1
|
|
option( options )
-
optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
1
|
|
widget()Returns: jQuery
jQuery
object containing the original element.-
This method does not accept any arguments.
Invoke the widget method:
1
|
|
Events
close( event, ui )Type: tooltipclose
focusout
or mouseleave
.Initialize the tooltip with the close callback specified:
1
2
3
|
|
Bind an event listener to the tooltipclose event:
1
|
|
create( event, ui )Type: tooltipcreate
Initialize the tooltip with the create callback specified:
1
2
3
|
|
Bind an event listener to the tooltipcreate event:
1
|
|
open( event, ui )Type: tooltipopen
focusin
or mouseover
.Initialize the tooltip with the open callback specified:
1
2
3
|
|
Bind an event listener to the tooltipopen event:
1
|
|
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
|
|