JavaScript CSS

README.md

zebrajs

Zebra_Tooltips

A lightweight and highly configurable jQuery tooltips plugin

npm Total Monthly License

Zebra_Tooltips is a lightweight (around 6KB minified, 1.9KB gzipped) jQuery tooltips plugin, featuring nice transitions and offering a wide range of configuration options. The plugin detects the edges of the browser window and makes sure that the tooltips always stay in the viewport.

Besides the default behavior of tooltips showing when user hovers the element, tooltips may also be shown and hidden programmatically using the API. When shown programmatically, the tooltips will feature a "close" button and clicking it will be the only way of closing tooltips opened this way. This is very useful for drawing users' attention to specific areas of a website (like error messages after validating a form).

By default, the plugin will use the "title" attribute of the element for the tooltip's content, but the tooltip's content can also be specified via the zebra-tooltip data attribute, or programmatically. Tooltips' appearance can be easily customized both through JavaScript and/or CSS. Tooltips can be aligned left, center or right, relative to the parent element.

Zebra_Tooltips uses NO IMAGES and falls back gracefully for browsers that don't support all the fancy stuff; also, tooltips can be attached to any element not just anchor tags!

Works in all major browsers (Firefox, Opera, Safari, Chrome, Internet Explorer 6+)

Screenshot

Support the development of this project

Donate

Features

  • lightweight - it weights around 6KB minified and 1.9KB gzipped
  • features nice transitions
  • detects the edges of the browser window and makes sure that the tooltips always stay in the viewport
  • tooltips may be shown and hidden using the API
  • appearance can be easily customized both through exposed JavaScript properties and/or CSS
  • tooltips can be aligned left, center or right, relative to the parent element
  • uses NO IMAGES and falls back gracefully for browsers that don't support all the fancy stuff
  • can be attached to any elements not just anchors
  • works in all major browsers (Firefox, Opera, Safari, Chrome, Internet Explorer 6+)

Requirements

Zebra_Tooltips has no dependencies other than jQuery 1.7+

Installation

Zebra_Tooltips is available as a npm package. To install it use:

npm install zebra_tooltips

Zebra_Tooltips is also available as a Bower package. To install it use:

bower install zebra_tooltips

How to use

First, load the latest version of jQuery from a CDN and provide a fallback to a local source, like:

<script src="https://code.jquery.com/jquery-3.2.1.min.js"></script>
<script>window.jQuery || document.write('<script src="path/to/jquery-3.2.1.js"><\/script>')</script>

Load the Zebra_Tooltips plugin

<script type="text/javascript" src="path/to/zebra_tooltips.min.js"></script>

Load the plugin's style sheet file

<link rel="stylesheet" href="path/to/zebra_tooltips.min.css" type="text/css">

Now, within the DOM-ready event do

$(document).ready(function() {

    // show tooltips for any element that has a class named "tooltips"
    // the content of the tooltip will be taken from the element's "title" attribute
    new $.Zebra_Tooltips($('.tooltips'));

});

Configuration options

Properties

Property Type Default Description
animation_speed integer 250 The speed (in milliseconds) of the animation used to show/hide tooltips.
animation_offset integer 20 The number of pixels the tooltips should use to slide into position.
Set to 0 for no sliding.
background_color string #000 Tooltip's background color.
May be a hexadecimal color (like #BADA55) or a supported named color (like limegreen).
close_on_click boolean TRUE By default, if the users clicks when over a tooltip, the tooltip will close (if the tooltip was not open using the API, that is).
Set this property to FALSE to prevent this behavior.
color string #FFF Tooltip's text color.
May be a hexadecimal color (like #FFF) or a supported named color (like white).
content string "" The content of the tooltip.
Usually, the content of the tooltip is given in the title attribute or as the zebra-tooltip data attribute of the element the tooltip is attached to.
Setting this property to FALSE will use the property's value as the content of all the tooltips rather than using the values of the title or the data attribute.
default_position string above By default, tooltips are shown above the elements they are attached to and are shown below only if there isn't enough space above.
Set the value of this property to below if you want to reverse the default behavior so that tooltips will be shown below the elements they are attached to and will be shown above only there isn't enough space below.
Possible values are above and below.
hide_delay integer 100 The delay (in milliseconds) after which to hide the tooltip once the mouse moves away from the trigger element or the tooltip.
keep_visible boolean TRUE Should tooltips remain visible also when the mouse cursor is over the tooltips or should the tooltips be visible strictly when the mouse cursor is over the parent elements.
max_width integer 250 Maximum width of the tooltip's content
opacity float 0.85 The tooltip's opacity.
Must be a value between 0 (completely transparent) and 1 (completely opaque)
position string center The tooltip's position, relative to the trigger element.
Can be any of the following:
  • center
  • left
  • right
prerender boolean FALSE If set to TRUE, tooltips will be created on document load, rather than only when needed.
show_delay integer 100 The delay (in milliseconds) after which to show the tooltip once the mouse is over the trigger element.
  • center
  • left
  • right
vertical_offset integer 0 How close (in pixels) should the tip of the tooltip be relative to the parent element.

Events

Event Description
onBeforeHide Event fired before a tooltip is hidden.
The callback function receives as argument the element the tooltip is attached to, and the tooltip element.
onHide Event fired after a tooltip is hidden.
The callback function receives as argument the element the tooltip is attached to, and the tooltip element.
onBeforeShow Event fired before a tooltip is shown.
The callback function receives as argument the element the tooltip is attached to, and the tooltip element.
onShow Event fired after a tooltip is shown.
The callback function receives as argument the element the tooltip is attached to, and the tooltip element.

Methods

show(element, [destroy = FALSE])

Shows the tooltip attached to the element or the elements given as argument.

When showing a tooltip using this method, the tooltip can only be closed by the user clicking on the "close" icon on the tooltip (which is automatically added when using this method) or by calling the hide() method.

Arguments

element - an element or a collection of elements for which to show the attached tooltips.

destroy - (optional) - if set to TRUE, once the user clicks the close button, the tooltip will be muted and will not be shown anymore when the user hovers the parent element with the mouse.

In this case, the tooltip can be shown again only by calling this method.

If set to FALSE, the tooltip will be shown whenever the user hovers the parent element with the mouse, only it will not have the close button anymore.

Default is FALSE

var element = $('#tooltip'),
    zt = new $.Zebra_Tooltips(element);

zt.show(element);

hide(element, [destroy = FALSE])

Hides the tooltip attached to the element or the elements given as argument.

When showing a tooltip using this method, the tooltip can only be closed by the user clicking on the "close" icon on the tooltip (which is automatically added when using this method) or by calling the hide() method.

Arguments

element - an element or a collection of elements for which to hide the attached tooltips.

destroy - (optional) - if set to TRUE, once hidden, the tooltip will be muted and will not be shown anymore when the user hovers the parent element with the mouse.

In this case, the tooltip can be shown again only by calling the show() method.

Default is FALSE

var element = $('#tooltip'),
    zt = new $.Zebra_Tooltips(element);

zt.hide(element);

Demo

See the demos