Visit the site » Introducing qTip2... the successor to Simpletip!
A simple jQuery tooltip plugin by Craig Thompson
 

Demos

Simple tooltips

Here's some examples of simple tooltips using some of the default options provided by the simpletip library.
Hover over me to see a bog standard tooltip using all default options.   $("JQUERY SELECTOR").simpletip();
Hover over me to see a fixed position tooltip.   $("JQUERY SELECTOR").simpletip({ fixed: true });
Click to see a persistent tooltip that only closes when clicked! Click the link or the tooltip to close it.   $("JQUERY SELECTOR").simpletip({ persistent: true });
Here's a tooltip with some custom content. Click the link or tooltip to close it.   $("JQUERY SELECTOR").simpletip({ persistent: true, content: '<img src="/projects/simpletip/images/logo_small.png" />' });

Positioning

When using static tooltips (e.g. fixed: true; configuration) there are several options available to position the tooltip. There are several pre-defined types such as top and right:
Hover over me to see a tooltip positioned to the left of the parent element.   $("JQUERY SELECTOR").simpletip({ fixed: true, position: 'left' });
Hover over me to see a tooltip positioned to the right of the parent element.   $("JQUERY SELECTOR").simpletip({ fixed: true, position: 'right' });
Hover over me to see a tooltip positioned to the top of the parent element.   $("JQUERY SELECTOR").simpletip({ fixed: true, position: 'top' });
Hover over me to see a tooltip positioned to the bottom of the parent element.   $("JQUERY SELECTOR").simpletip({ fixed: true, position: 'bottom' });
Also available is the option of user-defined absolute and/or relative positions using coordinate arrays e.g. absolute: [posX, posY], relative: ["posX", "posY"] or mixed: ["posX", posY]/[posX, "posY"] e.g.
This tooltip is absolutely positioned at coordinates [100, 730].   $("JQUERY SELECTOR").simpletip({ fixed: true, position: [100, 730] });
This tooltip is relatively positioned to its parent element at coordinates ["0", "-100"].   $("JQUERY SELECTOR").simpletip({ fixed: true, position: ["0", "-100"] });
You can even mix relative and positive positions! Here's a mixed coordinate tooltip at ["40", 740].   $("JQUERY SELECTOR").simpletip({ fixed: true, position: ["40", 740] });
If your using the predefined positions above (top, bottom etc.) you can adjust the position using the offset property, which takes the form a [posX, posY] array as seen in earlier positioning examples, as shown below:
This new tooltip is positioned to the right, but adjusted with an offset of [30, 0].   $("JQUERY SELECTOR").simpletip({ position: 'right', offset: [30, 0] });

Effects

Currently there are only two effects available by default in jQuery's base effects library, fade and slide:
Here's a pretty basic tooltip applied with the slide effect.   $("JQUERY SELECTOR").simpletip({ showEffect: 'slide', hideEffect: 'slide', position: 'top' });
Here's another tooltip with the default fade effect.   $("JQUERY SELECTOR").simpletip({ position: 'top' });
Separate effects can be applied to show and hide events, like this slide-in fade-out tooltip.   $("JQUERY SELECTOR").simpletip({ fixed: true, position: 'right', showEffect: 'slide', hideEffect: 'fade' });
Fortunately, there is also the option of custom methods for hiding and showing your tooltips! This is achieved by the use of the 'custom' showEffect/hideEffect property and the showCustom and hideCustom method callbacks, which are fired when the tooltip is shown or hidden. Examples:
Applying a custom show effect using the showEffect and showCustom properties.   $("JQUERY SELECTOR").simpletip({ position: 'bottom', showEffect: 'custom', showCustom: function(){ // Note the this attribute refers to the tooltip itself $(this).css({ fontSize: '12px', display: 'block' }) .animate({ fontSize: '20px' }, 400); } });
Applying custom effects on both show and hide.   $("JQUERY SELECTOR").simpletip({ position: 'bottom', showEffect: 'custom', hideEffect: 'custom', showCustom: function(){ // Note the this attribute refers to the tooltip itself $(this).animate({ width: '150px', opacity: 1, display: 'block' }, 400); }, hideCustom: function(){ // Note the this attribute refers to the tooltip itself $(this).animate({ width: '100px', opacity: 0, display: 'none' }, 400); } });
If you require the hideTime or showTime properties you defined, they can be accessed as an argument of the custom callback function:
This new tooltip utilises the your configurations showTime property via a method argument.   $("JQUERY SELECTOR").simpletip({ position: 'bottom', showEffect: 'custom', // Note the argument (showTime) in the function definition showCustom: function(showTime){ $(this).css({ borderWidth: 'inherit', fontSize: '12px', display: 'block' }) .animate({ borderWidth: 4, fontSize: '16px' }, showTime); } });

Dynamic content

Data can be stored in an array and easily used to create tooltips with different content using a single jQuery selector.
Content for this tooltip is different from this and this, but all are selected with the same jQuery selector!   // Setup a content array for the tooltips var arrayData = ['Content for tooltip 1', 'Content for tooltip 2', 'Content for tooltip 3']; $("JQUERY SELECTOR").each(function(i){ $(this).simpletip({ content: arrayData[i] }); });
Using the library's API update() method we can update the content of the tooltip at any time.
This tooltip content is updated everytime it's shown with the number of seconds passed in the minute.   $("JQUERY SELECTOR").simpletip({ onBeforeShow: function(){ // Note this refers to the API in the callback function var curDate = new Date(); this.update(curDate.getSeconds() + ' seconds have elapsed in this minute.'); } });
Content for each tooltip can also be loaded remotely using the library's API load() method, which utilises AJAX to retrieve content from a remote file.
The content of this tooltip is loaded from a local file named content.txt.   // Note the extra .simpletip() call to access the api var api = $("JQUERY SELECTOR").simpletip().simpletip(); // Load the content using the API load() method api.load('content.txt');
Content can also be loaded just before the tooltip is shown to reduce overhead.   $("JQUERY SELECTOR").simpletip({ onBeforeShow: function(){ // Note this refers to the API in the callback function this.load('content.txt'); } });

Documentation

Overview

Simpletip is a plugin for the popular jQuery JavaScript library. It allows you to create tooltips with ease on any element on the page using the power of jQuery's selectors and event management. The tooltips can be static, dynamic, or even loaded through AJAX with a variety of different visual effects.

Configuration

There are many other ways of using this tool than the demos provided here. It is important to realize that any element can have a simpletip assigned to it! Simpletip is always styled and instantiated with following:
  /* JavaScript code */ // Selects one or more elements to assign a simpletip to $("JQUERY SELECTOR").simpletip({ // Configuration properties content: 'My Simpletip', fixed: false });   /* CSS rules */ // Default tooltip class name: .tooltip .tooltip{ position: absolute; top: 0; left: 0; z-index: 3; display: none; }
 
The tooltip must be absolutely positioned for the positioning to work correctly. If you are having problems with tooltips not showing or being positioned correctly this is most likely the cause of it!

Configuration properties

Name Description Possible values Default value
content The HTML content which will appear inside the tooltip. Valid HTML A simple tooltip
persistent If set to true the tooltip will activate onclick rather than the default onhover behaviour. true or false false
focus For use with the persistent config option. If set to true the tooltip will stay active (on screen) until the document is clicked elsewhere. If false, tooltip will also close when clicked. true or false false
hidden If set to false the tooltip will be shown immediately when created. Works well with persistent. true or false true
 
position Determines how the tooltip is positioned relative to the element it is shown on. An array of x, y can be used set an absolute position. Encapsulating them in a string e.g. ["0", "0"] causes the positioning to be done relative to the top left corner of the root element. An HTML element can also be passed as an argument and it's current position assumed by the tooltip. default
top, bottom
left, right
absolute: [x, y]
relative: ["x", "y"]
mixed: ["x", y] / [x, "y"]
HTML element
default
offset Array of x, y by which to offset the tooltips position relative to that calculated by the position property. Array of any 2 integers [0, 0]
boundryCheck If true positioning will take into account window height and width to ensure tooltip does not scroll off page e.g. is always visible.

NOTE: Set this to false if your experiencing jittering on non-fixed tooltips
true or false true
fixed If set to false the tooltip moves with mouse as long as mouse is hovered over the root element. true or false true
 
showEffect Type of show effect to use. fade, slide, none fade
hideEffect Type of hide effect to use. fade, slide, none fade
showTime Time in milliseconds for showEffect effect. Positive integer 150
hideTime Time in milliseconds for hideEffect effect. Positive integer 150
showCustom Used along with the showEffect: 'custom' property. Custom method called when tooltip is shown. Defined method null
hideCustom Used along with the hideEffect: 'custom' property. Custom method called when tooltip is hidden. Defined method null
 
baseClass Class name to apply to generated tooltip elements supplied without the dot prefix. Any valid class name tooltip
activeClass Class name to apply to active (currently shown) tooltip elements supplied without the dot prefix. Any valid class name active
fixedClass Class name to apply to tooltip elements which move with the mouse i.e. non-static supplied without the dot prefix. Any valid class name fixed
persistentClass Class name to apply to presistent tooltip elements supplied without the dot prefix. Any valid class name persistent
focusClass Class name to apply to persistent focus tooltip elements supplied without the dot prefix. Any valid class name focus
 
onBeforeShow Callback method to execute before tooltip is shown. Defined method function(){}
onShow Callback method to execute after tooltip is shown. Defined method function(){}
onBeforeHide Callback method to execute before tooltip is hidden. Defined method function(){}
onHide Callback method to execute after tooltip is hidden. Defined method function(){}
beforeContentLoad Callback method to execute before content is loaded using the load method. Defined method function(){}
onContentLoad Callback method to execute after content is loaded using the load method. Defined method function(){}

Callback functions

The Simpletip library provides several key callback functions as part of it's API, allowing you to extend the functionality of the library with custom methods. Below is an example utilising the onShow method to change the content an element:    $("JQUERY SELECTOR").simpletip({ // onShow method - change content of parent element onShow: function(){ this.getParent().text('My content changes when my tooltip appears!') } // Configuration properties content: 'My Simpletip' }); Checkout the demos page for more examples.

Scripting API

The Simpletip comes with a great scripting API for users. A lot of effort has been made to make sure you have the necessary functionality to enrich the library with as little effort as possible. Once you've setup your simpletip on your element(s) the API can be accessed via the simpletip() call. An example of this is below:    // Create your tooltips $('JQUERY SELECTOR').simpletip(); // Access the API of a previously initatied simpletip var api = $('JQUERY SELECTOR').eq(0).simpletip(); // Perform a simple API call to update tooltip contents api.update('New tooltip content!'); Here's a list of all API methods available to you in the library:
Method Arguments Return value Description
getVersion() [x, x, x] Returns the version number of the Simpletip library currently in use.
getParent() Object Returns the element which the tooltip is associated with e.g. the element on which the simpletip() method was called.
getTooltip() Object Returns the tooltip element.
 
getPos() [top, left] Returns the absolute current position of the tooltip element.
setPos() posX, posY Simpletip Sets position of tooltip to absolute arguments posX and posY if supplied as integers, or relative to parent element if supplied as strings. A mixture of both strings and integers can also be used.
 
show() Simpletip Displays the tooltip element.
hide() Simpletip Hides the tooltip element.
 
update() content Simpletip Updates the contents of the tooltip element with the supplied argument, usually a string or integer.
load() url, data Simpletip Updates the contents of the tooltip element with the contents of a remote file url using AJAX. Use the data array to pass POST data on the AJAX call.

Browser support

  • Firefox 1.5+
  • Internet Explorer 6.0+
  • Safari 2.0+
  • Opera 9.0+

NOTE: This plugin requires the jQuery library to function, which can be downloaded here.

View/report issues Download stable 1.3.1

Link Size Description
jquery.simpletip-1.3.1.js 9.4 Kb source code - with comments
jquery.simpletip-1.3.1.min.js 5.0 Kb minified with Douglas Crockford's minifier
jquery.simpletip-1.3.1.pack.js 3.4 Kb packed with Dean Edward's packer
Please right click and choose "save link as ..." (or similar)

View/report issues Download Simple2 Beta

Checkout the Simpletip2 Sandbox site for the all new betas.

Changelog

Simpletip 1.3.1

level: Patch

released: February 5, 2009 - 11:04am

changelog:

  • Fixed major bug in relative position handling in 'updatePos' method
  • Added new 'hidden' configuration option to allow control over tooltips inital state (shown of hidden)
    Thanks to Benjamin for this feature suggestion

Simpletip 1.3

level: Minor

released: February 4, 2009 - 9:38pm

changelog:

  • Major overhaul of entire library
  • Brand new API functionality - see documentation for full details
  • Added pre-defined positioing properties
  • Added new 'custom' value to hideEffect and showEffect enabling custom show and hide methods
  • Added 'showCustom' and 'hideCustom' method callbacks for use with new 'custom' hideEffect/showEffect value functionality
  • Added new 'load()' API method to load remote file contents into tooltips
  • Added 'beforeContentLoad' and 'onContentLoad' callback methods: see 'load()'
  • Added new configuration option 'boundryCheck' to enable/disable boundry checking on a per-tooltip basis
  • Renamed 'hover' property to 'persistent' to better relay its purpose
  • Configuration option 'position' now accepts mixed array values of both absolute and relative positions
  • Configuration option 'position' now accepts an element reference as an argument, resulting in tooltip positioned at elements coordinates
  • Fixed several rendering bugs in Internet Explorer

Simpletip 1.2.2

level: Patch

released: February 4, 2009 - 7:44am

changelog:

  • Adjusted spelling error on 'baseClass' property

Simpletip 1.2.1

level: Patch

released: February 4, 2009 - 7:36am

changelog:

  • Renamed 'class' property to 'baseClass' due to problems with reserved keywords
    Special thanks to Justin for pointing out this error

Simpletip 1.2.0

level: Minor

released: February 3, 2009 - 4:17pm

changelog:

  • Added new positioning property
  • Fixed rendering bug
  • Adjusted contents property name, now called content (without the s)
  • Added individual show and hide effect time properties

Simpletip 1.1.0

level: Minor

released: February 2, 2009 - 6:38am

changelog:

  • Added window dimensions check to prevent offscreen rendering / scrolblar issues
  • Cleaned up code formatting
  • Removed updateHTML method. Main update method now manipulates HTML directly

Simpletip 1.0.0

level: Major

released: February 2, 2009 - 3:26am

changelog:

  • First major release