chrisdavies / tlite

A tiny tooltip utility library.

Tlite

Tlite is a small utility for displaying tooltips. (Check out the demo.)

• Around 800 bytes minified and gzipped
• 0 dependencies
• Uses event delegation, so it is fast and works with dynamic sites
• IE9+, FF, Safari, Chrome

There's also a pretty sweet CSS-only library which may do the trick, depending on your needs.

Usage

Include tlite.css or write your own. Include tlite.js. Then write some markup like this...

<button class="foo" title="Hi">Hover Here</button>

And invoke the tlite function to bind tlite to your page:

// Using es6 syntax, and classList. tlite should work
// in IE9+, but this sample won't!
tlite(el => el.classList.contains('foo'));

That will make any elements with a foo class show a tooltip when hovered.

Customize the tooltip's position

The tooltip can be positioned above, below, left, right, etc as follows:

<button class="foo" data-tlite="s" title="Hi">Hover Here</button>

The data-tlite attribute specifies the position, but it can also be specified in JavaScript:

// grav defaults to 'n' (below the target element)
tlite(el => { grav: 's' });

The grav property specifies the position of the tooltip possible values are:

• s - The tooltip shows above the target
• n - The tooltip shows below the target
• e - The tooltip shows left of the target
• w - The tooltip shows right of the target
• sw - The tooltip shows to top right of the target
• se - The tooltip shows to top left of the target
• nw - The tooltip shows to bottom right of the target
• ne - The tooltip shows to bottom left of the target

Manual controls

You can also manually trigger a show/hide of a tooltip:

// Show a tooltip beneath the target element
tlite.show(targetElement);

// Show a tooltip to the right of the target element
tlite.show(targetElement, { grav: 'w' });

// Hide it...
tlite.hide(targetElement);

Caveats

When the tooltip is displayed, it is inserted as a child of the element it is associated with. What this means is that tooltips cannot be displayed on contentless tags such as img, input, textarea, etc. The workaround is to put the toolltip on a wrapper element. This was done so that if an element is dynamically removed from the DOM, its tooltip goes with it.

If putting a tooltip inside of a table, you may want to put tlite-table class on the table to ensure proper positioning.

Tlite was really designed primarily for hover-based tooltips. If you display tlite tooltips on events other than hover (e.g. on focus or something), it is up to you to handle resize events (either repositioning the tooltip or hiding it), otherwise the tooltip could end up in an unexpected place.

Tlite does not escape your tooltip text. So, if you want to shove raw HTML in there, you can. But if you want to shove user-input in there, it is your job to ensure it is properly escaped!

Using something other than title

If you don't want to use the title attribute, you can use a data-tlite attribute, instead.

<button data-tlite="My Tooltip">Hover Over Me</button>

Installing

Download and include tlite.min.js

Or install using NPM:

npm install tlite

License MIT

Copyright (c) 2015 Chris Davies

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

tlite's Issues

suggestion for positioning

Not a real issue just a remark:

wouldn't it be more logical to have grave:'n' default to above the element? As in to the north of the element? I find it illogical that s is up, n is down, e is right and w is left.

Love your lib btw! =)

script DOM exceptions

In Safari I get

NotFoundError: DOM Exception 8

in Chrome I get

Failed to execute 'removeChild' on 'Node': The node to be removed is not a child of this node.

the error happens at tooltipEl && el.removeChild(tooltipEl);

      function hide(isAutoHiding) {
        if (isAuto === isAutoHiding) {
          showTimer = clearTimeout(showTimer);
          tooltipEl && el.removeChild(tooltipEl);
          tooltipEl = undefined;
        }
      }

I havn't reproduced the exact cause, however these errors are being tracked by our sentry.io instance

data-tlite doesn't seem to work

Tested in Chrome v. 65.0.3325.162

This may be a timing issue.

The data-tlite attribute doesn't seem to work, as it's somehow overridden as the element seems to be modified before createTooltip() is called. And at the point at which it's called, the attribute is now empty, even though I set it to a value of 'sw'.

Mobile device touch compatibility

Hello,

It need a small modification to keep as "manual" for touch screen.
It must work on hover for PC and on touch for mobile device.

Thanks

Allow specifying subset of document

For using tlite within widgets, it would be nice if we could configure where the event listener is placed. That way we could also ensure that nothing else on the website ends up blocking the event propagation.

tooltips for elements created by javascript?

Can I add tooltips to elements I've created and added via javascript? Could you provide an example?

southwest tooltip distance issue

When the browser window is very narrow on your home page (using osX/chrome), note that southwest's tooltip is higher than expected.

And here are the positions of the others (which all look good) for comparison:

tooltip for disabled button

tlite(function (el) { return el.classList.contains('foo'); });
document.body.innerHTML = '<button class="foo" title="Hi">Hover Here</button>';
document.querySelector( 'button' ).disabled = true;

http://codepen.io/jedierikb/pen/vXowXw?editors=0010

Results in an un-stylized tooltip showing up.
I was hoping no tooltip would show up.
What would be the best practice for preventing tooltips on a disabled button?

Live dynamic content

Hi,

Can I use it to display live changing dynamic data like bandwidth etc... (from my Socket.IO live client ) ?

(no ads) https://www.serveurperso.com/?page=robots

Pascal

Feature request: auto "grav"

Hi!
Thanks for this beautiful code :)

My sugest is: auto detect of element position "grav" like this...

 // this is actual method
 var grav = opts.grav || 'n';

 // I sugest this: use data- attribute
 var grav = opts.grav || el.getAttribute('data-tlite') || 'n';

This method allow configure multiple positions

switching tooltip text on click events shows browser default title

https://www.youtube.com/watch?v=gLo1zjf7D6Q
http://codepen.io/jedierikb/pen/xRxGNQ?editors=0011

var tip1 = true;
tlite(function (el) { 
  return el.classList.contains('foo');
});
document.body.innerHTML = '<button class="foo" title="tip1">Hover Here</button>';

var $b = document.querySelector('button');
$b.addEventListener( 'click', function() {
  tip1 = !tip1;
  tlite.hide( $b );
  $b.setAttribute( 'title', tip1 ? 'tip1' : 'tip2' );
  // tlite.show( $b );
});

I have no words

It is absolutely mind boggling that your js library for displaying tooltips doesn't actually contain function to display a tooltip on element, something like tlite.show(some_element, {text: "This is tooltip"}), I mean isn't displaying tooltips the very first thing someone wants from js tooltip library?

text = el.title || el.getAttribute(fallbackAttrib) || text || opts.text;

understanding window clipping

Your example tooltip wraps nicely when it encounters the edges of the window:

This trivial example does not:

(and here is the example: http://codepen.io/jedierikb/pen/mOdzjY?editors=0010)

tlite(function (el) { return el.classList.contains('foo'); });

document.body.innerHTML = '<button class="foo" title="I am a long tooltip but i get clipped :-(">Hover Here</button>';

How to use your tool to ensure tooltips are not clipped by the window?

window resize results in misplaced tooltip

Resizing a window can cause the tooltip to move away from its element. See video for example from your home page.

https://www.youtube.com/watch?v=IF85YsMhA4E

perhaps add a document resize listener to remove tooltips?

Doenst seem to work in a table cell

Okay, this time an actual issue =)

It seems that if I use the library with the test example and I add a table cell with a tooltip, for example

  <table>
    <tr>
      <td class="tooltip-n" title="test the tooltip">Tooltip will appear on the wrong place</td>
    </tr>
  </table>

the tooltip appears on the wrong position (usually somewhere top left).

indicator notch shifts 1px at end of css-opacity transtion

It is an occasional glitch on chrome

Details for fix here:
http://stackoverflow.com/questions/14729492/css3-transform-rotate-causing-1px-shift-in-chrome

Was able to fix by prevent by adding:

.tlite {
  ...
  -webkit-backface-visibility: hidden;
}