internetipstooltips without the whole kitchen sink

Why another tooltip library? We (the royal "we", as in my employer) needed something lightweight with minimal assumptions about integration, as well as dynamic repositioning (viewport edge detection), and pointer following. Most other libraries including these features are heavier than necessary, so we wrote our own. We also wanted something well tested, so internetips has pretty damn thorough coverage - in the neighborhood of 95%.

Why is it called internetips? 'Cause every other tooltip thing has "tool" in it, and that gets old.

Install

npm install internetips

If you're using SASS and the node_modules directory is setup in your includePaths, you can @import 'internetips/lib/style'. Otherwise, you should include the styles from dist/style.css into your page another way. See styles.css.

API

You must use the API to trigger tooltips, and there are no DOM bindings out of the box. Most libraries come with presets like "add class X", or use attribute data-tooltip="abc" to trigger a tooltip. This library makes no assumptions, and you're free to trigger a tooltip whenever/however you want.

Use the live-editor below to play around with different configuration options.

/** * If including via node: var internetips = require('internetips'); * If including via browser build, 'internetips' is bound to window object. */ var node = document.querySelector('#btn-trigger'); node.addEventListener('mouseenter', function (ev) { internetips.show({ content: 'Something lovely in here', // effect: 'solid', // target: ev.target, // if 'effect' = 'solid', target is required // place: 'right', // type: 'dark', // classes: ['a-custom', 'list-of-classes'], // offsetX: 30, // offsetY: 30 }); }); node.addEventListener('mouseleave', internetips.hide);

.show({...})

Render the tooltip display to visible. Receives a single options object {} with declarations for the tooltip instance to be shown.

content | string required

Value options: any

Text content to display in the tooltip. Note, this can also be an HTML string.

effect | string optional

Value options: 'float' | 'solid'

Does the tooltip float (follow) the cursor while displayed, or should it automatically position against a DOM node? Default: 'float'

target | DOM node optional

Value options: document.querySelector('#anything')

If using effect solid, a target must be passed for the tooltip to position against.

place | string optional

Value options: 'top' | 'right' | 'bottom' | 'left'

If space is available within the viewport, force positioning the tooltip in this direction. Note, if space is unavailable to position the tooltip in the specified direction, auto-repositioning will always take precedence.

type | string optional (deprecated)

Value options: 'dark' | 'light'

If using the default bundled styles, a light and a dark theme are included. Default: 'dark'.

classes | array optional

Value options: ['string1', 'string2', ...]

An array of extra class names to append to the tooltip node. Use this to add classes for custom styling options. Default: []

offsetX | int optional

Value options: any integer

Position the tooltip on the X axis +/- this amount (in pixels) from default center. Default: 15

offsetY | int optional

Value options: any integer

Position the tooltip on the Y axis +/- this amount (in pixels) from default center. Default: 15

.setConfig({...})

Some defaults can be defined for properties that all tooltips will share when .show() is invoked. Note, if the property is specified in the options object of .show(options), the defaults will be overridden.

place | string 'top' | 'right' | 'bottom' | 'left'

type | string (deprecated) 'dark' | 'light'

classes | array ['string1', 'string2', ...]

offsetX | int any integer

offsetY | int any integer

.hide()

Hide the tooltip. Note, this just sets the tooltip to not be displayed on the page anymore, but does *not* remove the node from the DOM.

.destroy()

Completely tear down the tooltip instance.

Hidden-But-Not-Really-Things

If you're an OOP snob, you'll recognize that these should probably be private-ish methods. To which you'll kindly be directed to: this lovely tidbit from the python community.

Anyways - since testing is actually kind of important, instead of integrating this tooltip library and trying to inspect what occurs in the DOM (like inspecting position calculations, and/or what content is going to be displayed in the tooltip), a couple hooks are available for use during testing.

Note, these methods are intended for use during testing only. While they are available all the time, just... don't.

._defineTestHooks({...})

Hooks can be registered which will be invoked during show(), hide(), and destroy() calls. All hooks will be extracted from the passed in object. In order to nullify all registered hooks, simply invoke ._defineTestHooks() with no arguments.

onShow | function optional

Will receive param html, which is a stringified version of the HTML defining the tooltip instance. Use this during testing to check what the tooltip is actually showing.

onHide | function optional

Invoked with no arguments when the tooltip .hide() method is called.

onDestroy | function optional

Invoked with no arguments when the tooltip .destroy() method is called. Note: this also unbinds all currently configured hooks; logic being you should destroy() tooltips after a test run and you'll want to unbind all existing hooks anyways.

onReset | function optional

Invoked with no arguments when the tooltip is reset.

._inspectConfig()

Get a snapshot of the current default configurations.

._restoreConfigDefaults()

If default configurations were changed with .setConfig(), they can be reset by invoking _restoreConfigDefaults().