Tooltip

var tip = new Tooltip(content, [options]);

content

Type: String|Element

Tooltip content. Can be a text, an HTML string, or a DOM element. Will be used as innerHTML when a string, and .appendChild() when an element.

If you are inserting image elements, they need to have their dimensions defined (either with width & height attributes, or in CSS), otherwise the Tooltip will work with dimensions before the image load. You can also bind a load event to the image, and when it triggers call .updateSize() method.

[options]

Type: Object

Tooltip options object

Options

Default options are stored in Tooltip.defaults.

Tooltip.defaults = {
	baseClass:   'tooltip', // Base tooltip class name.
	typeClass:   null,      // Type tooltip class name.
	effectClass: null,      // Effect tooltip class name.
	inClass:     'in',      // Class used to transition stuff in.
	place:       'top',     // Default place.
	spacing:     null,      // Gap between target and tooltip.
	auto:        0          // Whether to automatically adjust place to fit into window.
};

baseClass

Type String Default tooltip

Base tooltip class that will be applied to tooltip element upon creation. This class should define tooltip's layout & dimensions, and shouldn't be changed.

typeClass

Type String Default null

Tooltip's type class that will be applied to tooltip element upon creation. This class should define only visual changes that don't affect layout & dimensions.

Can be changed dynamically with .type() method.

effectClass

Type String Default null

Tooltip's effect class that will be applied to tooltip element upon creation. This class - in a correlation with inClass - should define only tooltip transitions. Example fade transition:

.tooltip.fade { opacity: 0; transition: opacity 200ms ease-out; }
.tooltip.fade.in { opacity: 1; transition-duration: 100ms; }

Can be changed dynamically with .effect() method.

inClass

Type String Default in

Tooltip's class for "transitioning in" state. It is applied to tooltip when it is being shown. This class doesn't have to declare anything, it functions mostly as a helper selector for effect classes.

place

Type String Default top

This options specifies tooltip's growth direction. Tooltip supports this places:

• top, top-left, top right
• bottom, bottom-left, bottom-right
• left, left-top, left-bottom
• right, right-top, right-bottom

spacing

Type Integer Default null

Defines the gap between tooltip and target position, used mainly to properly display tooltip arrow. This gap is defined with a top property in tooltip's base class:

.tooltip {
	top: 10px; /* Defines the spacing between tooltip and target position */
}

But can be overridden with this option.

auto

Type Boolean Default false

When set to true, tooltip will check whether the current requested place is possible to display within window borders, and if not, it'll try to pick a better one.

Methods

Unless stated otherwise, all methods return tooltip object, making them chainable.

.content(content)

Change tooltip's content. If tooltip is visible, it'll automatically readjust it's dimensions and position.

• content String|Element Can be a text, escaped HTML string, or DOM element.

.position(x, y)

Position the tooltip on specific coordinates.

.position(element)

Position the tooltip while using an element as position target.

.show(element / x, y)

Show the tooltip, and optionally position it. When arguments are present, they are directly relayed to .position() method.

.hide()

Hide tooltip.

.toggle()

Hide when shown, show when hidden.

.attach(element)

Attach tooltip to DOM element. When tooltip is attached, .position() arguments are ignored and attached element is always used as a tooltip target position. When attached tooltip is visible, it is automatically repositioned on window resize.

.detach()

Detach tooltip from element.

.type(name)

Change type class. Pass falsy or no value to remove type class.

.effect(name)

Change effect class. Pass falsy or no value to remove effect class.

.changeClassType(type, name)

The underlying method used by .type() & .effect(). For example, the .type() method is basically just a:

Tooltip.prototype.type = function (name) {
	return this.changeClassType('type', name);
};

You can use this to create your own class types.

.place(name)

Change default tooltip place. When tooltip is visible, it is automatically repositioned to the requested place.

.updateSize()

Updates tip.width & tip.height properties to be in sync with the actual size of tooltip element. It is run on tooltip creation and automatically on .content() changes.

You'd want to use this when you are inserting a DOM element as a tooltip content, and than manipulating this element from outside. Whenever some layout change happens to that element, .updateSize() should be called.

Properties

element

Tooltip element. This element is detached from DOM when tooltip is hidden.

classes

A component/classes object handling tooltip element classes. You can do:

tip.classes.add('foo');
tip.classes.remove('foo');
tip.classes.toggle('foo');
tip.classes.has('foo');
tip.classes.array(); // returns an array of all current classes

hidden

Type Boolean

True when tooltip is hidden, false otherwise.

options

Tooltip options object.

spacing

Type Integer

Tooltip spacing - the additional gap between tooltip and it's target position. It is used to create a gap between tooltip and its target position so the tooltip arrow would not overlap the target. This value is a mirror of options.spacing when defined, or retrieved from baseClass's top style otherwise. For example, to have a 10px gap between tooltip and its target:

.tooltip {
	top: 10px;
}

You can also set it manually in options:

var tip = new Tooltip('foo', { spacing: 10 });
tip.show();

The purpose of the .tooltip:top weirdness is to have all layout declarations in CSS and out of JavaScript. As the arrow size is declared 100% in CSS, so should be the gap needed for its proper display.

width

Width of tooltip element. Updated by .updateSize() method.

height

Height of tooltip element. Updated by .updateSize() method.

attachedTo

Element the tooltip is attached to, otherwise null.