Customizable Interactive Tooltips In Pure JavaScript – Tippy.js

Preview:

Description:

Tippy.js is a small yet highly customizable JavaScript tooltip library that helps you add customizable, interactive, animated, accessible, touch-friendly tooltips to any DOM element.

Key features:

• Supports all positions: top, right, bottom left
• Custom trigger events: mouseenter, focus, click or manual.
• 4 built-in amazing animations: shift, perspective, fade or scale.
• 4 themes: Google, Light Border, Light, and Translucent
• Allows to embed any HTML markup inside the tooltip.
• Allows multiple tooltips on the same element.
• Useful callback functions.

Install it via NPM:

$ npm install tippy

Basic usage (v6):

Import the tippy library.

import tippy from 'tippy.js'; 
import 'tippy.js/dist/tippy.css';
// Additional Borders
import 'tippy.js/dist/border.css';

Or load the JavaScript files as displayed below in your html document.

<script src="https://unpkg.com/[email protected]"></script>
<script src="https://unpkg.com/[email protected]"></script>

Import themes as per your needs.

import 'tippy.js/themes/light.css';
import 'tippy.js/themes/light-border.css';
import 'tippy.js/themes/material.css';
import 'tippy.js/themes/translucent.css';

Add the ‘tippy’ class to your element and define the tooltip content using ‘data-tippy-content’ attribute like this:

<span class="tippy" data-tippy-content="I'm a tooltip!">Hover Me</span>

Initialize the tooltip library by creating a new Tippy object like this:

new Tippy('.tippy')

Config the tooltip using the following options. Note that all the options listed below are allowed to be passed via JavaScript or HTML data attributes:

new Tippy('.tippy', { 
    // enable accessibility
    a11y: true,
    aria: {
      // `null` when interactive is enabled
      content: 'auto', // `aria-*` attribute
      // `true` when interactive is enabled
      expanded: 'auto', // `aria-expanded` attribute
    },
    role: 'tooltip',
    // allows html content
    allowHTML: false,
    // animate the background fill color
    animateFill: true,
    // more animation are:
    // import 'tippy.js/animations/scale.css';
    // import 'tippy.js/animations/scale-subtle.css';
    // import 'tippy.js/animations/scale-extreme.css';
    animation: 'fade',
    // where the tooltip should be appended to
    appendTo: () => document.body,
    
    // shows the tooltip arrow
    arrow: false,
    // "sharp", "round"
    arrowType: 'sharp',
    // "scrollParent", "window",  "viewport", or an HTMLElement
    boundary: 'scrollParent',
    // the content of the tippy
    // string,  Element, or Function
    content: '',
    // animation delay
    delay: 0,
    // distance & offset in pixels
    offset: [5, 10],
    // duration of the animation
    duration: [325, 275],
    // makes the tooltip always follow the cursor
    followCursor: false,
    // hides the tooltip on click
    hideOnClick: true,
    // ignores the data-tippy-* attribute
    ignoreAttributes: false,
    // applies an inertial slingshot effect to the animation
    inertia: false,
    // enables interactive tooltip
    interactive: false,
    interactiveBorder: 2,
    interactiveDebounce: 0,
    // max width 
    maxWidth: 350,
    // positions the tooltip
    placement: 'top',
    // popper.js options
    popperOptions: {},
    
    // shows the tooltip on init
    showOnCreate: false,
    // "small", "regular", "large"
    size: 'regular',
    // target CSS selector
    target: '',
    // theme name
    // 'light', 'light-border', 'material', 'translucent'
    theme: '',
    // enables touch events
    touch: true,
    // custom trigger events
    trigger: 'mouseenter focus',
    // target trigger element
    triggerTarget: null,
    // move transition
    moveTransition: 'transform 0.2s ease-out',
    // z-index property
    zIndex: 9999
    
})

Via HTML ‘data-tippy-OPTION’ attributes:

<span class="tippy" 
      title="I'm a tooltip!"
      data-tippy-OPTION="VALUE">
      Hover Me
</span>

Callback functions available:

new Tippy('.tippy', { 
    onAfterUpdate: function onAfterUpdate() {},
    onBeforeUpdate: function onBeforeUpdate() {},
    onCreate: function onCreate() {},
    onDestroy: function onDestroy() {},
    onHidden: function onHidden() {},
    onHide: function onHide() {},
    onMount: function onMount() {},
    onShow: function onShow() {},
    onShown: function onShown() {},
    onTrigger: function onTrigger() {},
    onUntrigger: function onUntrigger() {},
    onClickOutside: function(){}
    
})

API methods.

// show the tippy
instance.show()
// hide the tippy
instance.hide()
// programmatically hook into interactive behavior upon a mouseleave event if implementing custom event listeners
instance.hideWithInteractivity(mouseEvent);
// enable the tippy
instance.enable()
// disable the tippy
instance.disable()
// destroy the tippy
instance.destroy()
// unmount the tippy from the DOM
instance.unmount();
// update the tippy
instance.setProps({
  arrow: true,
  animation: 'scale',
})
// set new content
instance.setContent('New content')
// clear the instance's delay timeouts
instance.clearDelayTimeouts()

Changelog:

v6.3.7 (11/10/2021)

• fix: toggle repeated clicks with inner target element
• fix: change mounted state after true mount
• fix: check state only from hide
• fix(delegate): warnings in console with esm

v6.3.5 (11/06/2021)

• (createSingleton): triggerTarget prop and touch input issue

v6.3.4 (11/04/2021)

• (delegate): touch input with click trigger & hideOnClick
• [Firefox] clicking into a <select> inside an interactive tippy will not cause it to hide with mouseenter trigger

v6.3.3 (10/29/2021)

• Bugfix

v6.3.1 (02/26/2021)

• Fix issue with move / popper transitions in certain cases

v6.3.0 (02/23/2021)

• Add methods to singletons to control them programmatically
• Upgrade Popper dependency
• Bugfix

v6.2.7 (10/11/2020)

• Bugs fixed

v6.2.6 (07/29/2020)

• use getCurrentTarget() in interactivity hide listener
• move var assignment into hide() method
• (followCursor): wrong position if mouse was not moved initially
• (delegate): missing comparison check

v6.2.5 (07/09/2020)

• (followCursor): Fix setting getReferenceClientRect to null onHidden even if followCursor was not set (to a truthy value)

v6.2.4 (07/03/2020)

• More bugs fixed.

v6.2.2 (04/28/2020)

• (inlinePositioning): increased 1px buffer to 2px and fallback to standard technique instead of boundingRect

v6.2.1 (04/27/2020)

• Lots of bugs fixed

v6.2.0 (04/17/2020)

• createSingleton can have overrides prop and tippyInstances updated
• hideWithInteractivity method
• Allow contextElement property on getReferenceClientRect
• Bugs fixed

v6.1.1 (04/04/2020)

• Lots of bugs fixed

v6.1.0 (03/16/2020)

• Added ‘onClickOutside’ prop
• Added ‘dist/border.css’ stylesheet

v6.0.2 (03/11/2020)

• Bugs fixed.

v6.0.1 (03/06/2020)

• Bugs fixed.

v6.0.0 (03/01/2020)

• Compatible with popperjs v2.
• V5 to V6 migration guide is available here.

v5.2.1 (02/13/2020)

• hide tippy on focusout from child element
• improve hiding upon scroll with interactivity
• followCursor: scroll listeners for vertical/horizontal

v5.2.0 (01/31/2020)

• Add support for ‘focusin’ trigger

v5.2.0 (01/31/2020)

• Add support for ‘focusin’ trigger
• Prevent removing aria-expanded attribute if already present on the reference

v5.1.4 (01/14/2020)

• Make mouseenter click behaviour consistent for interactive/non-interactive tippies
• Fix onShown hook

v5.1.3 (12/29/2019)

• Bugs fixed.

v5.1.1 (11/04/2019)

• core: filter out duplicate plugins
• core: revert distance technique to use top/left properties
• inlinePositioning: works with .show() method
• types: refactor interfaces to generics, strict types for custom plugins

v5.1.0 (10/22/2019)

• Allow plugins passed as Props.plugins
• Deprecate createTippyWithPlugins() – use tippy.setDefaultProps({plugins: […]});

v5.0.4 (10/21/2019)

• core: Fix onWindowBlur condition
• core: Fix iife versions’ addons not having plugins passed by default
• followCursor: Allow .show() / .hide() to work
• types: Handle null in delay/duration arrays

v5.0.3 (10/14/2019)

• Lots of bugs fixed

v5.0.2 (10/07/2019)

• Bugs fixed

v5.0.1 (10/01/2019)

• core: Add support for iframe
• core: Use .currentTarget over .target
• core: Clear pending timeouts on destroy
• followCursor: Use rAF instead of setTimeout to avoid rare jitter on content update
• followCursor: reset popperInstance reference onHidden
• warnings: Ensure links end with trailing slash
• types: Add missing type for createTippyWithPlugins

v5.0.0 (09/29/2019)

• Core size has decreased
• Better developer experience
• Animation improvements
• New touch: [“hold”, delay] prop (for long press behavior)
• New arrow: string | SVGElement values to use your own shape
• New createSingleton addon, supersedes group() for smooth transitions
• New sticky behavior to check reference or popper rects (or both)
• New inlinePositioning prop supports better inline element positioning (further behavior options to come)
• Allows you to extend functionality of tippy instances and create your own props.
• Improved accessibility out of the box
• Subtle behavioral bugs fixed and improvements made

v4.3.5 (08/02/2019)

• Optimize sticky option by preventing repaints on every animation frame
• Place injected style node before the first style or link tag instead of first child
• Reduce CSS size slightly
• Fix leak with document click listener not being removed if tippy was hidden before it was shown when using delay
• Add referenceNode property for followCursor

v4.3.3 (06/04/2019)

• Fix followCursor having incorrect offset when using a variation placement (-start or -end)

v4.3.2 (06/03/2019)

• Mounting behavior (IE11 scrollbar flicker)
• followCursor fixes (respects boundary & fix regression where initial was not placed correctly on touch devices on first show)
• Ensure destroy()’s unmounting of the tippy can never be impeded
• Fix the longstanding interactive scrolling issue
• Fix path selector having pointer-events: auto

v4.3.1 (05/11/2019)

• Improve support for nested tippys by using per-instance hideOnClick handler
• Add data-tippy-stylesheet to style tag

v3.4.0 (01/12/2019)

• Follow cursor additions

v3.3.0 (12/08/2018)

• Add maxWidth to updatePopperElement
• Refactor code into more sensible module

v3.2.0 (11/18/2018)

• Use state.isMounted over state.isVisible in destroy()

v3.1.1 (11/03/2018)

• New themes: `light-border` and `google`

v3.1.0 (10/12/2018)

• Fix setContent() resetting followCursor position

v3.0.3 (09/29/2018)

• Bugfix

v3.0.1 (09/24/2018)

• Bugfix

v2.6.0 (09/08/2018)

• Bugfix

v2.5.4 (07/14/2018)

• Bugfix