Tippy v5

The main goal of this version is to:

1. Improve developer experience with warnings without bloating production bundle size
2. Massively reduce core size and make the library more treeshake-able
3. Allow new feature additions to be added separately without increasing bundle size
4. Improve naming consistency and usage

Highlights

• ⬇️ 30%+ smaller download size (5.4 kB minzipped including core CSS)
• ⬇️ 50%+ smaller parse size (15.1 kB minified including core CSS)
• ⬇️ 60%+ smaller core CSS (0.6 kB minzipped) + smaller external animation files
• ⚙️ Development and production versions for better developer experience
• ✨ New animation variations
• ✨ New touch: ["hold", delay] prop (for long press behavior)
• ✨ New arrow: string | Element values to use your own shape
• ✨ New createSingleton method, supersedes group()
• 🌸 Improved animations integration and documentation, namely fully dynamic transition dimensions when tippy content updates
• 🌸 Improved naming consistency
• ♿ Improved accessibility defaults for interactive tippys
• 🐛 Various minor behavior bug fixes

Development and production versions of Tippy.js

We're now adding helpful development warnings without bloating bundle size. Development files are .js, while production versions are .min.js.

Main filename was renamed from index.all to tippy.bundle for better DevTools display.

tippy.js/
├── dist/
│   ├── tippy.cjs.js              "main" file
│   ├── tippy.esm.js              "module" file
│   ├── tippy-bundle.iife.js              
│   ├── tippy-bundle.iife.min.js         "unpkg" file
│   ├── tippy.iife.js              
│   ├── tippy.iife.min.js

// This whole block will get stripped by minifiers/DCE for production builds
// When importing like `import tippy from 'tippy.js'`
if (process.env.NODE_ENV !== 'production') {
  if (somethingBad) {
    console.warn('You did somethingBad');
  }
}

Where's the umd folder? The browser format is now iife. Node is covered by cjs, and amd is dead and/or didn't work with popper.js/tippy.js anyway before because of the .js suffix apparently (which is what umd covered). Now it's not necessary.

iife development version includes the block without the Node-only process variable. In the .min version, it's stripped out entirely (like the other formats).

Drop Android 4.4 support

Remove all -webkit- prefixed transforms to save 200 minzipped bytes or so.

Force data-placement and data-out-of-boundaries attributes

The inconsistency between data-animation and x-placement has been annoying. Since 4.2.0, we've moved these attributes to the .tippy-tooltip node, so we can rename them.

Default is now arrow: true and animation: 'fade'

Having animateFill: true and animation: 'shift-away' animation as defaults add a lot of CSS bloat. By making the "bootstrap" tooltip default a lot of code is stripped away.

Further reasons listed here: https://github.com/atomiks/tippyjs/pull/499#issuecomment-504662996

import tippy from 'tippy.js';
import 'tippy.js/dist/backdrop.css';
import 'tippy.js/animations/shift-away.css';

tippy(targets, {
  content: 'tooltip',
  animateFill: true,
  animation: 'shift-away'
});

If using a custom SVG arrow, import the SVG arrow CSS

Again, for treeshaking reasons, not everyone cares about SVG arrows, so will need to import the CSS separately:

import 'tippy.js/dist/svg-arrow.css';

Delays are always 0 in touch and keyboard contexts

I don't see a reason to keep delay here, it's poor UX. If people require this to be configured then we can add it later.

Remove target option and tippy.group() from core

They've been moved into a file called "addons" to conserve core's size. createSingleton has replaced group since its behavior is better and allows transitions since a single tippy is being used.

Functions in this bundled file should be treeshaken by bundlers.

import {delegate, createSingleton} from 'tippy.js';

delegate('#parent', {
  target: 'button'
});

const singleton = createSingleton(tippy('button'), {
  delay: 500
});

Move followCursor to plugins

Like the "addons", props are being moved to separate parts because not everyone needs this behavior.

import tippy, {followCursor} from 'tippy.js';

tippy.use(followCursor);

Animations

A ton of work has been gone into considering animations more deeply.

This includes:

• CSS transitions (default)
• CSS animations (e.g. animate.css)
• JavaScript and spring animations (e.g. animejs)
• FLIP animations of tippy content (e.g. react-flip-toolkit/core)

Default CSS animations: shift-toward, scale, perspective animations removed

Only fade will remain in tippy.css.

Extra CSS animations will be moved to a folder called animations/ (like themes/); there are now 3 variants of each animation expect for fade (subtle and extreme added).

Example import:

import 'tippy.js/animations/shift-away-subtle.css';

CSS animations (instead of transitions - e.g. animate.css)

We're now using use top/left/right/bottom: 10px as the base distance offset, rather than specifying it in the transform. Makes it more compatible with external animation CSS, FLIP libraries, and removes need for the notransition technique.

There's no need to think about distance anymore now due to this.

tippy('button', {
  // `fade` is now just an opacity transition, which is a good base for most
  // animations.
  animation: 'fade',
  onMount(instance) {
    const {tooltip} = instance.popperChildren;
    requestAnimationFrame(() => {
      tooltip.classList.add('animated', 'wobble');
    });
  },
  onHidden(instance) {
    const {tooltip} = instance.popperChildren;
    tooltip.classList.remove('animated', 'wobble');
  }
});

Dimensions transition

⚠️ Highly experimental code. There are tons of edge cases I've had to work out. Hopefully this can be wrapped in a simple addon API.

See demo/flip

Remaining problems:

• Work out the dynamic clip-path based on the placement needed to prevent content overflowing when the tippy has an arrow (since it can't have overflow: hidden).
• Work out how to make it fully dynamic, considering .setProps() method.

Themes

• google theme was renamed to material, to remove the association with Google.
• Prevent the need to specify .tippy-tooltip[data-animatefill] .tippy-backdrop selector (to make background-color transparent)

New lifecycle functions

• onCreate
• onUntrigger
• onPropsUpdated
• onDestroy

Virtual reference elements

Plain objects are not supported anymore - instead, you just pass a placeholder element like this:

const placeholderElement = document.createElement('div');

// IE9+ supports overriding this method. That's all that's needed for
// Popper.js to position the tippy.
//
// `client{Width,Height}` when 0 (i.e. not appended to the document) do not have an effect,
// as Popper.js falls back to the dimensions instead
placeholderElement.getBoundingClientRect = () => ({ ... });

tippy(placeholderElement, options);

This conserves size since we don't need to polyfill element methods in the plain object.

Auto built index.d.ts

Internal types don't live in types.ts so now index.d.ts gets generated on build, which is just a copy of src/types.ts.

Naming

The term "options" is being completely ditched in favor of "props" everywhere. And now consistent methods:

• instance.set() was renamed to instance.setProps()
• tippy.defaults was renamed to tippy.defaultProps
• tippy.setDefaults() was renamed to tippy.setDefaultProps()

This directly aligns with the React component model since every prop is dynamic and updateable. Options are now Partial, or termed "optional props". The merged interface is Props as it was before.

• showOnInit -> showOnCreate to match lifecycle hook

New static property

tippy.currentInput is a mutable object with a single property isTouch. This moves the internal isUsingTouch flag to this object so that users can access it, as it's sometimes useful in rare cases.

i.e. tippy.currentInput.isTouch

New accessibility defaults for interactive tippys

By default if interactive: true, then: {aria: null, appendTo: "parent"}

There's also a warning in DEV if the tippy is not directly after the ref/triggerTarget node. If the user specifies a different appendTo, then it gets ignored as it assumes there are clipping issues and they need a custom focus management solution to handle it.

• aria-expanded attribute also added
• aria-describedby handles multiple tippys

TODO

5.1.0 goals:

• Wrap animejs logic in an addon wrapper
• Wrap FLIP animation library logic in an addon wrapper, hopefully solve the 2 remaining problems

Current experimental React wrapper

Hi everyone,

The next version of Tippy.js is coming in August. In order to ensure it's as stable as possible, I need you to help test it out.

Poll

How are you using the tippy.js package? Answer here if you get time! #550

Goals

1. Improve developer experience with warnings without bloating production bundle size
2. Massively reduce core size and make the library more treeshake-able
3. Allow new feature additions to be added separately without increasing bundle size
4. Improve naming consistency and usage

Highlights

• ⬇️ 26% smaller download size (5.8 kB minzipped including core CSS)
• ⬇️ 46% smaller parse size (16.9 kB minified including core CSS)
• ⬇️ 61% smaller core CSS (0.6 kB minzipped) + smaller external animation files
• ⚙️Development and production versions for better developer experience
• ✨New animation variations
• ✨New touch: ["hold", delay] prop (for long press behavior)
• ✨New arrow: string | Element values to use your own shape
• ✨New createSingleton method, supersedes group()
• 🌸Improved animations integration and documentation, namely fully dynamic transition dimensions when tippy content updates
• 🌸Improved naming consistency

Installation

Package Managers:

# npm
npm i tippy.js@next

# Yarn
yarn add tippy.js@next

CDN:

<script src="https://unpkg.com/popper.js@1"></script>
<script src="https://unpkg.com/tippy.js@next"></script>

Changes

View all of the details in the PR in progress.

Migration Guide

<script src="https://unpkg.com/popper.js@1"></script>
<!-- Specify development file -->
<script src="https://unpkg.com/tippy.js@5/iife/tippy.bundle.js"></script>
<!-- 
When you're finished, you can remove everything after @5 
(or when deploying for production) 
<script src="https://unpkg.com/tippy.js@5"></script>
-->

import tippy from 'tippy.js'; // <— fine
import tippy from 'tippy.js/esm/index.min.js'; // <— breaking

import tippy from 'tippy.js';
import 'tippy.js/backdrop.css';
import 'tippy.js/animations/shift-away.css';

tippy(targets, {
  content: 'tooltip',
  animateFill: true,
  animation: 'shift-away'
});

<link rel="stylesheet" href="https://unpkg.com/tippy.js@5/backdrop.css" />
<link
  rel="stylesheet"
  href="https://unpkg.com/tippy.js@5/animations/shift-away.css"
/>
<script src="https://unpkg.com/popper.js@1"></script>
<script src="https://unpkg.com/tippy.js@5"></script>
<script>
  tippy(targets, {
    content: 'tooltip',
    animateFill: true,
    animation: 'shift-away'
  });
</script>

import 'tippy.js/svg-arrow.css';

tippy(targets, {
  arrow: 'round'
});

<link rel="stylesheet" href="https://unpkg.com/tippy.js@5/svg-arrow.css" />

import tippyBase from 'tippy.js';
import enhance, {followCursor} from 'tippy.js/extra-props';

const tippy = enhance(tippyBase, [followCursor]);

tippy('button', {followCursor: true});

<script src="https://unpkg.com/popper.js@1"></script>
<script src="https://unpkg.com/tippy.js@5"></script>
<script src="https://unpkg.com/tippy.js@5/extra-props/iife/tippy-extra-props.min.js"></script>
<script>
  tippy('button', {followCursor: true});
</script>

- import tippy from 'tippy.js';
- tippy.group(tippy('button'), { delay: 1000 });
+ import { createSingleton } from 'tippy.js/addons';
+ createSingleton(tippy('button'), { delay: 1000 });

<script src="https://unpkg.com/popper.js@1"></script>
<script src="https://unpkg.com/tippy.js@5"></script>
<script src="https://unpkg.com/tippy.js@5/addons/iife/tippy-addons.min.js"></script>
<script>
  tippy.createSingleton(tippy('button'), {delay: 1000});
</script>

- import tippy from 'tippy.js';
- tippy('#parent', { target: '.child });
+ import { delegate } from 'tippy.js/addons';
+ delegate('#parent', { target: '.child' });

<script src="https://unpkg.com/popper.js@1"></script>
<script src="https://unpkg.com/tippy.js@5"></script>
<script src="https://unpkg.com/tippy.js@5/addons/iife/tippy-addons.min.js"></script>
<script>
  tippy.delegate('#parent', {target: '.child'});
</script>

import 'tippy.js/animations/scale.css';

<link
  rel="stylesheet"
  href="https://unpkg.com/tippy.js@5/animations/scale.css"
/>

tippy(document.createElement('div'));

- instance.set({});
+ instance.setProps({});

- tippy.defaults;
+ tippy.defaultProps;

- tippy.setDefaults({});
+ tippy.setDefaultProps({});

@Prnda1976

Can you check this out and play with it to see if it's all good?

It wasn't as hard as I thought. The mouseenter focus gets switched to mouseover focusin (for bubbling). The popper instance gets re-used so performance is increased. One slight thing I noticed is that because it's re-used, there can't be two tooltips on the page so it will instantly "hide"/transition out if the cursor went to the next target. Not that big of a deal though...

EDIT: To use dynamic titles:

<div id="parent" title="_">
  <div class="child" data-title="one">text</div>
  <div class="child" data-title="two">text</div>
  <div class="child" data-title="three">text</div>
  <div class="child" data-title="four">text</div>
</div>

tippy('#parent', {
  target: '.child',
  onShow() {
    const content = this.querySelector('.tippy-content')
    content.innerHTML = this._reference.getAttribute('data-title')
  }
})

My employer has recently hired very talented consultants to evaluate how accessible our software is. They've also evaluated tippy since it's part of that product. Mostly the review came back pretty clean, but they flagged a few issues related to some aria-* property declarations.

Would this feedback be something you'd be interested in? I'm happy to forward the tippy specific stuff if you'd find that useful.

I was able to solve #726 and #720 without (or very unlikely) breaking changes!

Compatibility: Styles should remain the same due to:

• ::before element now inherits from text color of arrow, but it was probably never changed by users. (No usage)
• added ::after element which is transparent as long as border-color of arrow element is not changed, which is also unlikely to be changed by users, since it had no effect on the styles
• even if these changes were made, themes have priority through stronger CSS selectors

There is a probability of a break in custom themes (i.e if someone made similar changes I did), but I really doubt it.

Feature: basic styles + added user CSS:

.tippy-box {
  border: darkcyan solid 1px;
  background-color: lightblue;
}
.tippy-arrow {
  border-color: darkcyan;
  color: lightblue;
}

You have following effect

Without border:

.tippy-box {
  background-color: lightblue;
}
.tippy-arrow {
  color: lightblue;
}

Btw. This feature highly improves #725 plugin because it is no longer necessary to create style tag.

Core

• Rename performance option to ignoreAttributes
• Remove arrowTransform option
• Remove tippy.useCapture() & tippy.disableAnimations()
• Remove tippy.one() and collections, return the instance directly if Element or VirtualElement, otherwise array of the instances
• tippy.hideAllPoppers() renamed to tippy.hideAll() and ignores hideOnClick value for static method consumers
• CSS simplified, opinionated CSS like font-smoothing removed
• tippy.group() method
• In event delegation mode, content and appendTo as functions receive the target element rather than the delegate reference
• updateDuration: 0 by default so flips don't have the weird transition, and specifying any number uses true smooth flips (with no problem on IE11 now)
• MutationObserver removed, .set() calls scheduleUpdate() now, and if changing a HTML element as the content, the user should manually call .scheduleUpdate() or use a ResizeObserver polyfill for complete update accuracy
• Flipping has changed. livePlacement was renamed to flipScroll and now position does still update on scroll, but it doesn't flip while scrolling. Flipping while scrolling is now disabled by default since it's better UX, I think.
• Remove all focus handling: leave it up to the developer. Recommended option requires no focus handling: append it directly after the trigger so elements can be tabbed to. There may be some stacking issues where it needs to be appended to the body, but they can programmatically .focus() it if need be and make it act like a modal.

Package

• Babel 7
• popper.js is external in all files and formats
• 4 formats: -- index.js = tippy -- index.min.js = tippy minified -- index.all.js = tippy + css -- index.all.min.js = tippy + css minified
• Files are no longer nested under dist and exist in the root directory, aka

tippy.js/
├── umd/
│   ├── index.js
│   ├── ...
├── esm/
│   ├── index.js
│   ├── ...
├── themes/
│   ├── light.css
│   ├── ...
├── index.css
├── index.d.ts
├── LICENSE
├── README.md
├── package.json

I think we should default to the injectCSS method for modules as well, no need to import CSS manually - thoughts?:

{
  "main": "./umd/index.all.min.js",
  "module": "./esm/index.all.js"
}

Use minified code for "main" field (since sourcemaps anyway?), so CDN include looks like this:

<script src="https://unpkg.com/popper.js@1/dist/umd/popper.min.js"></script>
<script src="https://unpkg.com/tippy.js@4"></script>

Examples:

// A: Uses esm format + injects CSS
import tippy from 'tippy.js'

// B: Uses cjs format + import css
const tippy = require('tippy.js/umd/index.js')
require('tippy.js/index.css')

Minzipped bundle sizes look like:

JS: 5.93 kB CSS: 1.56 kB

/cc @KubaJastrz

Let me know what kind changes you would like to see.

V1 didn't have any input from people so I'd like to prepare a bit better, such as the improving the naming of things, use cases, etc.

To align more with Popper.js I'm thinking:

JS:

• data objects for each tooltip should rename the el property (the element given the tooltip) to reference (like Popper does)
• getReferenceData() should just be getData()? (I had trouble trying to decide what it should be before)
• Rename settings to options throughout (this seems to be more standard from what I've seen)
• Get rid of src from package, add ESM/UMD files
• Naming convention cleanup. I think going all lowercase makes things simple. tippy.Browser.SUPPORTED / tippy.Defaults should probably just be tippy.browser.supported and tippy.defaults?

CSS:

• Switch from enter / leave "global" classes to data attributes, like data-state="show" / data-state="hide"? Or x-state?
• Rename arrow classes (.arrow-big etc) and use large in favor of big
• Animation/Theme plugins for more options?
• Also how about injecting CSS to the document straight from the JS to simplify it even further? Not sure if this is bad practice though.

Hi,

My website is a song database. Each songs have 3 types of opinion (up / like / down). With that system, our DJs can give their opinions. When a use click give it's opinion, i update the title. The website uses turbolinks to ensure a continued audio play. So my tippy instance is not destroyed during navigation.

My problem are:

• auto update of title (but they are already a bug on that)
• append to an existing Tippy instance, the new songs added by the infinite scroll. I can destroy but not add a tooltip to an existing instance.

I would like to do : tip.add("CSS selector")

Is there a good way of doing that ?

thanks

• Linting (ESLint): Add .eslintignore (Useful for IDE to avoid flagging when browsing files)
• Linting (ESLint): Apply ESLint to rollup.build.js
• Linting (ESLint): Fix error of missing done in test file (though test is in the ignore file to avoid flagging lesser errors)
• Linting (npm): Add linter-recommended contributors, bugs, homepage, and engines properties (some of these used on npmjs.com)
• Linting (HTML): Avoid favicon request in console

As far as the test linting errors, I personally think it would be better to ensure you are catching any errors there (if not in website too), but as it didn't appear to be your intent to lint them, I've added test and website to .eslintignore as well as the dist paths.

See above for the other rationales of inclusion.

I plan to provide a more substantive PR for modules after this.

Hi, I decided to use your lib and had found some strange behaviour when target element is inside block with scrollable overflow and body is scrolled too.

Here is screenshot http://prntscr.com/f0ks7j.

How to reproduce:

1. Goto https://jsbin.com/cuvagihudu/edit?html,css,js,output
2. Scroll body to the end.
3. Scroll .container to the end
4. Hover "Hover me, i'm broken!" button and check the position of the tooltip.

Looks like this case doesn't take into account the body's or document's scrollOffset

I'm having a tooltip template which I add to some elements in the document ready event. Is it possible to add that tooltip to dynamically created elements that are generated afterwards?

Bug description

Tippy provides a way to add border around the popout through border.css. When added in the above suggested way the arrows are not ending with the container level, the arrow ending are extended into the container.

This issue is more noticeable when the tippy is shown on the right or bottom of the reference element.

Reproduction

CodePen link: https://codepen.io/Monisha98/pen/eYjJZza Click on the button to open the tippy in general it could be seen the arrows are not ending evenly. If not the issue can be reproducible through zoom.

I have an input inside tippy content but the on-change is not firing

<input (ngModelChange)="onSearchQueryChange($event)" />

CodePen link: https://codepen.io/atomiks/pen/yvwQyZ

Add a "disabling animations" section to the animations page, so that it's more easier for the new users to find this option.

Let me know if there's anything else I need to do on this PR 😉

In the documentation for plugins you recommend to useKeyboardEvent.keyCode however this is deprecated, the current advice is to use KeyboardEvent.code. So I have updated the docs to reflect this very minor change.

Problem

Tip delegation doesn't do anything with an SSR app using Nuxt3, even with elements available at load time and dynamic elements.

<div id="tippyRoot">
<App/>
</div

<a
     data-tippy-content="Learn More About Schema.org"
     href="https://schema.org/"
     target="_blank"
     >Schema.org</a>

delegate("#tippyRoot", {
        target: "[data-tippy-content]",
        content: 'loading',
        animation: "scale",
        trigger:'hover',
        onShown(instance) {
          instance.setContent(instance.reference.dataset.tippyContent);
        },
 });

All elements have the appropriate data attribute but nothing seems to work.

Solution

Seems like delegate would do the job but something is off. even setting a timeout before initializing doesn't work to make sure everything is loaded. Any suggestions or documentation on how to use this library with Nuxt3? Love the library but after we switched to SSR I'm having a ton of issues getting it to work.