Javascript Tooltip Library

cordinc_tooltip.js is a simple, free javascript library based on Prototype for displaying tooltips in a browser. The tooltip will appear after a mouseover event on the trigger element and disappear after a mouseout event. It can handle Scriptaculous Sortable elements which can cause problems in other libraries. It has been tested on Firefox 2/3 & IE6/7.

To add tooltips to your web page first include the tooltip and Prototype 1.6 javascript libraries to your page:

<script src="../scripts/prototype.js" type="text/javascript"></script>
<script src="../scripts/tooltip.js" type="text/javascript"></script>

Then the items you want to have tooltips will require a unique CSS id to identify them (elements with non-unique ids may fail to display on some browsers). After that it is simply a matter of a short script to specify the target and the CSS id of the element to act as the tooltip, plus any options The code snippet below created this example:

tooltip text here
<div id="tooltipTarget" style="background: #A6FFA3; width: 20px; height: 20px;"></div>
<div id="tip_basic" class="tooltip">tooltip text here</div>
<script type="text/javascript">new Tooltip('tooltipTarget', 'tip_basic', {className: 'tooltip'})</script>

If the item with the tooltip is a Scriptaculous Sortable or other element that is often redrawn then you need to use the option DOM_location to place the tooltip outside the redrawn area so that it is in a higher z-index stacking context (for example, off your main CSS container): DOM_location: {parentId: "toolTipContainer", successorId: "beforeToolTip"}.

For more information see the API section.

It is possible to change the location the tooltip will be shown relative to the target element. The hook option specifies the corners on the target element and tooltip that will be made closest to eachother (before the offset is applied). By default this option is set to {target:'topRight', tip:'bottomLeft'}.

hook: {target:'topRight', tip:'bottomLeft'}
hook: {target:'topMid', tip:'bottomMid'}
hook: {target:'topLeft', tip:'bottomRight'}
hook: {target:'leftMid', tip:'rightMid'}
hook: {target:'rightMid', tip:'leftMid'}
hook: {target:'bottomLeft', tip:'topRight'}
hook: {target:'bottomMid', tip:'topMid'}
hook: {target:'bottomRight', tip:'topLeft'}

It is possible to specify both start and end effects, to occur just after the tooltip appears and disappears respectively. Just specify a function start_effect or end_effect in the tooltip options, eg new Tooltip('starteffect', 'tip_starteffect', { start_effect: function(element) {element.shake();} }). Both methods should accept single parameter which is the tooltip being displayed (a copy of the original tooltip). By default there are no start or end effects. Start effect example using Scriptaculous shake:

Start effect example:

End effect example using Scriptaculous puff (note that this has an end delay applied so that it is possible to see the end effect before the tooltip disappears):

End effect example:

start_effect: function(element) {element.shake();}
end_effect: function(element) {element.puff();}, delay: {start: 0, end: 1}

If the element next to which the tooltip will be displayed is not the element which should trigger the tooltip, then this can be specifued with the trigger option. If specified, the mouseovers on the trigger element will cause the tooltip to be displayed on the target element. By default the trigger and target elements are the same.
trigger: other

It is possible to define a delay before the tooltip appears or disappers using the delay option. The start delay is the number of seconds that the mouse needs to be over the trigger element before the tooltip appears, and the end delay is the number of seconds after the mouse has left the target element before the tooltip is removed (this is handy for end effects). The default is zero seconds for both start and end delay.
delay: {start: 1, end: 2}

To fine-tune the position of the tooltip use the offset option. This specifies a x & y coordinate offset from the normal position of the tooltip. The default offset is 0.
offset: {x: -5, y: -5}

This code is available under the Opensource BSD license. Copyright (c) 2009 Charles Cordingley.

cordinc_tooltip.js can be downloaded here.

The call to create a tooltip is:
new Tooltip(<unique ID of the element on which the tooltip will be displayed>, <ID of the tooltip element>, {<options>})

The destroy() method on the tooltip can be used to cleanup up the remove the tooltip and stop listening to events.

classNamenoneThe CSS class to apply to the tooltip
delay{start: 0, end: 0}Time (in seconds) to wait before displaying (the start option) or removing (the end option) the tooltip
DOM_locationnoneLocation in the document DOM to place the tooltip (Can be used to avoid problems with zindex stacking contexts)
end_effectfunction(element) {}Function to run on the tooltip immediately before it is removed
hook{target:'topRight', tip:'bottomLeft'}Location the tooltip will be shown relative to the target element
offset{x:0, y:0}The x & y coordinate offset from the normal position of the tooltip
start_effectfunction(element) {}Function to run on the tooltip immediately before it is displayed
triggerThe element for which mouse events will trigger display of the tooltip, if different to the tooltip target
zindex1000The z-index of the tooltip when displayed. Normally this would not need to change