Developer Network Home - Help

YUI 2: Tooltip

YUI 2: Tooltip

The Tooltip control is an extension of Overlay that is analogous to popup tooltips within common operating systems. The standard tooltip interaction pattern involves a small overlay that is displayed when the mouse hovers over a context element for a specified amount of time. Tooltip is designed to be simple to implement with easily-accessed configuration options and visual styling handled entirely via CSS.

Getting Started

To use Tooltip, include the following code in your page:

  1. <!-- CSS -->
  2. <link rel="stylesheet" type="text/css" href="https://yui-s.yahooapis.com/2.9.0/build/container/assets/container.css">
  3.  
  4. <!-- Dependencies -->
  5. <script src="https://yui-s.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
  6.  
  7. <!-- OPTIONAL: Animation (only required if using ContainerEffect) -->
  8. <script src="https://yui-s.yahooapis.com/2.9.0/build/animation/animation-min.js"></script>
  9.  
  10. <!-- Source file -->
  11. <script src="https://yui-s.yahooapis.com/2.9.0/build/container/container-min.js"></script>
  12.  
<!-- CSS -->
<link rel="stylesheet" type="text/css" href="https://yui-s.yahooapis.com/2.9.0/build/container/assets/container.css">
 
<!-- Dependencies -->
<script src="https://yui-s.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
 
<!-- OPTIONAL: Animation (only required if using ContainerEffect) -->
<script src="https://yui-s.yahooapis.com/2.9.0/build/animation/animation-min.js"></script>
 
<!-- Source file -->
<script src="https://yui-s.yahooapis.com/2.9.0/build/container/container-min.js"></script>
 
Next, apply the yui-skin-sam class name to an element that is a parent of the element in which the Tooltip Control lives. You can usually accomplish this simply by putting the class on the <body> tag:

  1. <body class="yui-skin-sam">
  2.  
<body class="yui-skin-sam">
 

For more information on skinning YUI components and making use of default skins, see our Understanding YUI Skins article here on the website.

YUI dependency configurator.

YUI Dependency Configurator:

Instead of copying and pasting the filepaths above, try letting the YUI dependency Configurator determine the optimal file list for your desired components; the Configurator uses YUI Loader to write out the full HTML for including the precise files you need for your implementation.

Note: If you wish to include this component via the YUI Loader, its module name is container. (Click here for the full list of module names for YUI Loader.)

Where these files come from: The files included using the text above will be served from Yahoo! servers; see "Serving YUI Files from Yahoo!" for important information about this service. JavaScript files are minified, meaning that comments and white space have been removed to make them more efficient to download. To use the full, commented versions or the -debug versions of YUI JavaScript files, please download the library distribution and host the files on your own server.

Order matters: As is the case generally with JavaScript and CSS, order matters; these files should be included in the order specified above. If you include files in the wrong order, errors may result.

Using Tooltip

This section describes common tasks for creating and using Tooltip. It contains these sections:

Tooltip inherits its constructor and configuration, as well as several other important methods, from Overlay. See Overlay for more information on how to utilize Tooltip's inherited features.

Initializing the Tooltip

Tooltips require no existing HTML markup, as they are created entirely in JavaScript. However, a Tooltip is invoked when the user hovers over a specific HTML element. The HTML ID of that related element — we'll call that the context element — must be supplied to the Tooltip constructor and it must exist on the page prior to instantiating your Tooltip.

Assuming, then, that there is a context element on the page with an HTML ID of myContextEl, you can instantiate a Tooltip this way:

  1. myTooltip = new YAHOO.widget.Tooltip("myTooltip", {
  2. context: "myContextEl",
  3. text: "You have hovered over myContextEl.",
  4. showDelay: 500
  5. });
  6.  
myTooltip = new YAHOO.widget.Tooltip("myTooltip", { 
    context: "myContextEl", 
    text: "You have hovered over myContextEl.",
    showDelay: 500
});
 

This example specifies a Tooltip that reads "You have hovered over myContextEl." It displays when the user hovers the mouse over the HTML element whose ID is myContextEl for at least half a second. Note: Since Tooltips are generated dynamically, the ID passed to the constructor in the first argument (myTooltip in the example above) is assigned to the HTML ID attribute of the container element created by the Tooltip control for this Tooltip when it is rendered.

Setting the Tooltip Text

You can set text that displays in the Tooltip in two ways:

  1. <img id="context" src="image.gif" title="My tooltip text"/>
  2.  
<img id="context" src="image.gif" title="My tooltip text"/>
 
  1. // 1. Using the "text" property
  2. var myTooltip = new YAHOO.widget.Tooltip("myTooltip", {
  3. context: "myContextEl",
  4. text: "Some tooltip text"
  5. });
  6. // 2. Using the "title" attribute in your context element
  7. // If no value is specified for the Tooltip's "text" configuration property,
  8. // it will be derived from the title attribute of the context element
  9. var myTooltip = new YAHOO.widget.Tooltip("myTooltip", {
  10. context: "context"
  11. });
  12.  
// 1. Using the "text" property
var myTooltip = new YAHOO.widget.Tooltip("myTooltip", {
    context: "myContextEl",
    text: "Some tooltip text"
});
// 2. Using the "title" attribute in your context element
// If no value is specified for the Tooltip's "text" configuration property,
// it will be derived from the title attribute of the context element
var myTooltip = new YAHOO.widget.Tooltip("myTooltip", {
    context: "context"
});
 

Rendering the Tooltip

The Tooltip is automatically rendered in an invisible state after the document has finished loading; it appears when the user hovers over its context element with the mouse.

Configuration Properties

Tooltip has the following configuration properties:

Name TypeDefaultDescription
text String null Specifies the Tooltip's text.
context String / Element (Array) null Specifies the element or elements that the Tooltip should be anchored to on mouseover.
container String / Element document.body Specifies the container element that the Tooltip's markup should be rendered into.
preventoverlap Boolean true Specifies whether the Tooltip should be kept from overlapping its context element.
showdelay Number 200 The number of milliseconds to wait before showing a Tooltip on mouseover.
hidedelay Number 250 The number of milliseconds to wait before hiding a Tooltip after mouseout.
autodismissdelay Number 5000 The number of milliseconds to wait before automatically dismissing a Tooltip after the mouse has been resting on the context element.
disabled Boolean false If true, the tooltip will not be displayed when the user mouses over context elements.
xyoffset Array [0, 25] The XY distance in pixels by which to offset the Tooltip from the mouse position, when shown.

Tooltip has the following inherited configuration properties (with default value changes noted in bold):

Name TypeDefaultDescription
visible Boolean false Sets whether or not the Tooltip is visible on the page (Tooltip uses the CSS "visibility" property to control this).
effect Object / Object[] none Sets the ContainerEffect (one or many) that should be used when showing and hiding the Tooltip
monitorresize Boolean true Configures whether or not to create a hidden off-screen element that can be used to monitor for text size changes in the DOM
x Number null Sets the element's page X co-ordinate.
y Number null Sets the element's page Y co-ordinate.
xy Array null Sets the element's page XY co-ordinates.
fixedcenter Boolean false Specifies whether the Overlay should be automatically centered in the viewport on window scroll and resize.
width String null Sets the element's "width" style property.
height String null Sets the element's "height" style property.
zIndex Number null Sets the element's "z-index" style property.
constraintoviewport Boolean true If set to true the Overlay will try to remain inside the confines of the size of viewport.
iframe Boolean false (true by default for IE 6 and below) If set to true the Menu will have and iframe behind it to prevent other elements with a higher z-index from poking through.

Support & Community

The YUI Library and related topics are discussed on the on the YUILibrary.com forums.

Also be sure to check out YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.

Container Family Examples:

Other YUI Examples That Make Use of the Container Family:

YUI Tooltip on del.icio.us:

bookmark on del.icio.us

be the first to bookmark this page!

Copyright © 2016 Yahoo! Inc. All rights reserved.

Privacy Policy - Copyright Policy - Job Openings