Developer Network Home - Help

Yahoo! UI Library: Tooltip

Yahoo! UI Library: 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:

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 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 "CSS skins": One of the files listed above contains a CSS "skin" for the Tooltip Control. For this skin CSS to work correctly, you will need to apply the CSS class "yui-skin-sam" to an element that is a parent of the element in which the component lives. You can usually accomplish this simply by putting the class on the <body> tag:

<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.

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:

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:

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.

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 "left" style property.
y Number null Sets the element's "top" style property.
xy Array null Sets the element's "top" and "left" style properties.
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 ydn-javascript mailing list.

In addition, please visit the 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 YUI SourceForge project 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:

Copyright © 2008 Yahoo! Inc. All rights reserved.

Privacy Policy - Terms of Service - Copyright Policy - Job Openings