• 

  Simple
• 

  Style
• 

  

  

  Round
• 

  

  

  Stems
• 

  Element

  The tooltip is a common graphical user interface element. It is used in conjunction with a cursor, usually a mouse pointer. The user hovers the cursor over an item, without clicking it, and a small box appears with supplementary information regarding the item being hovered over.

  

  Source: Wikipedia
• 

  

  

  Hooking
• 

  Target
• 

  

  Buttons
• 

  Events
• 

  

  Click
• 

  Delay
• 

  Hide after
• 

  Offset
• 

  Ajax
• 

  Viewport

Upload all the files from the Prototip package to your server. The images, CSS and the Javascript. If you decide on a different folder structure you will need to set the correct paths by changing these lines in prototip.js:

images: '../../images/prototip/',
javascript: ''

Make sure you have a valid doctype set as the very first line on the page. We recommend using the HTML5 doctype:

Prototip requires Prototype 1.7+. In the example below I'm including Prototype using the Google AJAX Libraries API. As an alternative you could download and host Prototype yourself, but by including it using Google's AJAX Libraries API you don't have to worry about caching and bandwidth cost.

Add Prototip below Prototype, the correct order is as in the example below.

<script type='text/javascript' 
src='https://ajax.googleapis.com/ajax/libs/prototype/1/prototype.js'></script>
<script type='text/javascript' src='/js/prototip/prototip.js'></script>

Add prototip.css to your header.

<link rel="stylesheet" type="text/css" href="css/prototip.css" />

tip: The Google Ajax Libraries API can be used to automatically load the latest version of Prototype. To do this you change the last part of the url to /1.7/prototype.js for the latest 1.7.* release, or /1/prototype.js for the latest 1.* release.

Creating a tooltip is as easy as:

new Tip(element, 'content');

To create a more advanced tooltip you can add an optional thirth parameter with options:

new Tip(element, 'content', {
  title: 'This tooltip has a title',
  style: 'protoblue',
  stem: 'topLeft',
  hook: { tip: 'topLeft', mouse: true },
  offset: { x: 14, y: 14 }
});

note: See the documentation for all the available options.

Hooking allows you to place your tooltips anywhere in relation to your target elements. The concept is simple, you define two corners that you want to 'hook' to eachother. One on the target element, the other one on the tooltip.

hook: { target: 'bottomRight', tip: 'topLeft' }

You can also hook your tooltip to the mouse pointer. Offset can be used to prevent the tooltip from appearing directly under the mouse icon.

hook: { tip: 'topLeft', mouse: true },
offset: { x: 14, y: 14 }

•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  

note: When hooking is used on elements tooltips won't try to stay within the viewport.

new Tip(element, { stem: 'topLeft' });

note: The same positions can be used with hooking.

Ajax tooltips allow you to pull content from an url, keeping your code clean. The content argument is left out when you use ajax. Use url to set the location for the Ajax Request. The options parameter can hold anything you would otherwise set on an Ajax.Request as options. See the Prototype API on Ajax.options and Ajax.Request for more details.

new Tip(element, {
  ajax: {
    url: '/include/ajax.php',
    options: {
      onComplete: function() { alert('ajax content loaded'); }
    }
  }
});

The following examples are a bit more advanced. The custom events prototip:shown and prototip:hidden allow you to call a function when tooltips open or close. You can do this by observing the element that opens the tooltip. If you have firebug installed you can run the examples below from your console, this one works on the first demonstration.

$('demo_simple').observe('prototip:shown', function() {
  this.pulsate({ pulses: 1, duration: 0.3 });
});

Custom events bubble up so can monitor the document for them. This makes it possible to monitor all tooltips at once. Here's how to call a function when every tooltip hides.

document.observe('prototip:hidden', function(event) {
  event.element().shake(); // our target element, we shake it with Scriptaculous
});

note: Scriptaculous is used to create the effects in the custom event examples.

To make it a bit easier to manage tooltips you can create them automatically based on a CSS condition. Here's how to do this for every link in the page using rel attibutes, after the page has finished loading. Since $$ accepts a CSS selector it could also be used to target different groups of elements.

document.observe('dom:loaded', function() {
  $$('a[rel]').each(function(element) {
    new Tip(element, element.rel);
  });
});

tip: The above example shows just a fraction of what's possible with Prototype. I recommend reading up on Prototype as much as you can, it's a beautiful framework that will make your coding experience a lot more enjoyable.

new Tip(element, content[, options]);

• element

  An id or an element.

  new Tip('myId', 'text'); // id
  new Tip($('myId').down('span.myclass'), 'text'); // element

• content

  A string or an element.

  new Tip('myId', 'text to go into the tooltip'); // id
  new Tip('myId', new Element('div').update('my text')); // element

• options

  Optional object with options, see the documentation on Tip.options

The following options can be used to customize a tooltip.

• ajax

  Pull content from an url using an Ajax.Request. An object containing url and optional options. Where options are the options can would normally set on an Ajax request using Ajax.options.

  new Tip('myId', {
    ajax: {
      url: 'page.php',
      options: {
        method: 'get',
        onComplete: function() { alert('loaded ajax content'); }
      }
    }
  });

  note: The content argument is left out, since Ajax will get this for you.

• border

  The size of the border in pixels. If the radius is bigger than the border you have currently set the border will become bigger.

  border: 6

• borderColor

  A CSS color string.

  borderColor: '#cccccc'

• closeButton

  true or false. Show or hide the closebutton.

• delay

  Delay when showing the tooltip in seconds. Default 0.14, so you can safely hover your page.

• fixed

  Set this to true if you don't want the tooltip to follow the mouse.

• hideAfter

  Hide the tooltip after a time of inactivity in seconds. This means your tooltip will hide after the element or the tooltip is not hovered for this duration.

• hideOn

  A string with the event to use, or an object allowing more control, or false.

  hideOn: 'mouseout'
  hideOn: { element: 'target', event: 'mouseout' }
  hideOn: { element: 'tip', event: 'mousemove' }
  hideOn: { element: 'closeButton', event: 'click' } // inserts closebutton
  hideOn: { element: '.close', event: 'click' } // 'close' becomes closebutton
  hideOn: false // useful in combination with hideAfter

• hideOthers

  When true, will hide all other tooltips before opening.

• hook

  An object hooking two elements together. See hooking for more details and demonstrations.

  hook: { target: 'topRight', tip: 'bottomLeft' }
  hook: { target: 'rightMiddle', tip: 'leftMiddle' }
  hook: { tip: 'bottomRight', mouse: true }

• images

  This allows you to set a different image directory for the tooltip, or for a style when used in Prototip.Styles.

  images: 'styles/custom/'
  images: '../../someDirectory/styles/custom/'
  images: 'http://www.yoururl.com/prototip/styles/custom/'

• offset

  An object containing the x and y offset you want to give to the tooltip.

  offset: { x: 16, y: 44 }

• radius

  The corner radius of the border in pixels. If the radius is bigger than the border you have currently set the border will become bigger.

  radius: 6

• showOn

  The event that shows the tooltip. Default: 'mousemove'.

  showOn: 'click'

• stem

  A string with the stem position, an object giving more control, or false. See stems for more details on stem positions.

  stem: 'topLeft'
  stem: 'leftMiddle'
  stem: { position: 'bottomRight', width: 14, height: 16 }

• style

  The style to use for the tooltip, defined in Prototip.Styles. Default: 'default'.

• target

  An id or an element that will function as the target for your tooltip. Default: the element in the Tip call.

  target: 'myId'
  target: $('myId').up('li.row')

• title

  A string with the title or the tooltip, this will insert the toolbar containing the title.

• viewport

  Keep the tooltip within the viewport. true or false.

  note: Tooltips that hook to elements will not stay within the viewport.

• width

  An integer to set the width of the tooltip in pixels, a css string like 'auto', or false. Default: false, sets the width defined in the CSS.

  width: 200
  width: 'auto'

• Tips.hideAll()

  Hide all visible tooltips on the page.

• Tips.remove(element)

  Remove the tooltip from an element.

  Tips.remove('myId'); // id
  Tips.remove($('myId').down('a[rel]')); // element

  note: Calling new Tip again on an element automatically uses Tips.remove on that element.

These options can be configured in prototip.js.

• images

  The path to the prototip image directory, can be relative to this file or an absolute url. An absolute url is often required when url rewriting is used.

  images: '../images/prototip/', // relative
  images: 'http://www.site.com/images/prototip/', // absolute

• zIndex

  The default zIndex of the tooltips. When you are hoving tooltips zIndex will automatically increase so tooltips will always be on top. The value used here will be the starting zIndex.

All elements you create a tooltip for are extended with a prototip object containing a few useful functions.

• prototip.show()

  Shows the tooltip set on the element.

  $('myId').prototip.show();

• prototip.hide()

  Hides the tooltip set on the element.

  $('myId').prototip.hide();

• prototip.remove()

  Removes the tooltip from the element, this also removes .prototip.

  $('myId').prototip.remove();

I use jQuery but Prototip doesn't work with it out of the box, it tells me to enable jQuery noConflict, how should I do that?

Since Prototip uses Prototype you'll have to enable jQuery.noConflict to avoid conflicts between jQuery and Prototype. You can find documentation about it on the jQuery website. Here's an example of a correct use of jQuery.noConflict so it works with third party code like Prototip:

<!-- Include jQuery -->
<script type='text/javascript' src='/js/jquery.min.js'></script>

<!-- Enable noConflict -->
<script type='text/javascript'>jQuery.noConflict();</script>

<!-- Other scripts can now safely use their own $ function -->
<script type='text/javascript' src='https://ajax.googleapis.com/ajax/libs/prototype/1/prototype.js'></script>
<script type='text/javascript' src='/js/prototip/prototip.js'></script>

Tip: If you are looking for a tooltip library that is jQuery based, have a look at Tipped.

I've enabled jQuery.noConflict but now some of my jQuery code doesn't work, how do I fix that?

Since the point of jQuery.noConflict is to remove the $ function out of the global scope and give it back to its original owner you should always use a closure that turns the jQuery object into the $ function. This makes it possible to use the jQuery object as the $ function within your own scope, making your code work with third party code. Here's an example:

(function($) {
  /* The jQuery $ function can be used here without conflict.
   * It's recommended to always use a closure like this so your jQuery code will work 
   * with third party code without having to modify anything later on.
   * 
   * jQuery plugins that are properly coded already use a closure like this. 
   */
   
   $(document).ready(function() { alert('this is jQuery'); });
})(jQuery);

$(document).observe('dom:loaded', function() { alert('this is Prototype'); });

Tooltips are not showing up.

Give your page a doctype, I recommend using the HTML5 doctype. Also make sure prototip.css is included.

My tooltips look different from those on the Prototip website.

This could be because prototip.css is not included or images are not uploaded. Make sure you image directory is set correctly in prototip.js. This also happens when your own css is conflicting with prototip.css. Remember not to set things globally in your own css files, rules like: li { display: inline; } are bad practice. Target your elements better, this will prevent conflicts. When your css is properly coded you should have no problem implementing Prototip.

It's still not working.

Make sure your page validates using validator.w3.org before posting for support on the Prototip Forum. I also recommend getting Firefox with the Firebug addon, many problems posted on the forum are easily solved with the debugging it provides.

Note: If you are looking for a jQuery based tooltip, have a look at my latest script: Tipped.

• Prototip 2.2.5

The latest changelog entries. Subscribe to the feed if you want to be notified of updates.

...

Use the Prototip Forum for support related questions, feedback, feature requests and bug reports.

For anything non-support related you can contact me at nick@nickstakenburg.com or @staaky. Please use the Forum to get support, I don't have the time to answer every support related email individualy.