Customizable Interactive Tooltips In Pure JavaScript – Tippy.js

Category: Javascript , Recommended , Tooltip | November 10, 2021
Author:atomiks
Views Total:3,200 views
Official Page:Go to website
Last Update:November 10, 2021
License:MIT

Preview:

Customizable Interactive Tooltips In Pure JavaScript – Tippy.js

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

You Might Be Interested In:


Leave a Reply