Fixes

• core: filter out duplicate plugins (#626)
• core: revert distance technique to use top/left properties (#628)
• inlinePositioning: works with .show() method (#630)
• types: refactor interfaces to generics, strict types for custom plugins, function overloading types for tippy and delegate

Features

• Allow plugins passed as Props.plugins

Deprecations

• Deprecate createTippyWithPlugins() - use tippy.setDefaultProps({plugins: [...]});

Fixes

• 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

Fixes

• core: Reduce impact of .tippy-iOS class side effects
• core: Improve support for nested tippies (CSS fixes + account for nested interactiveBorders)
• core: hideAll() works on <iframe>s
• props: distance should accept strings
• css: Switch to consistent px units
• warnings: Tweak invalid prop warning
• warnings: Tweak arrowType warning
• warnings: Fix target warning link

Fixes

• core: Only set transition duration to 0 upon show if not currently mounted (for createSingleton early cancelation)
• core: Plugin hooks for onShow and onHide invoked before props'
• core: Change distance technique to use padding on popper instead of top/left on tooltip
• css: Improve consistency of vars and units
• addons: Add support for plugins
• delegate: Account for data-tippy-trigger attribute
• createSingleton: Fix missing argument in onAfterUpdate to preserveInvocation()
• perf: Optimize data-tippy-* attribute reducer
• warnings: Add link to accessibility docs for interactive warning and improve clarity

Fixes

• core: Add support for iframes: atomiks/tippy.js-react#121
• 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

View migration guide from v4 to v5

Goals

1. Improve developer experience with warnings without bloating production bundle size
2. Massively reduce core size and make the library more tree shakeable
3. Allow new feature additions to be added separately without increasing bundle size (addons & plugins system)
4. Improve naming consistency and usage

Highlights

🌳 Core size has decreased

The library is now tree shakeable, allowing you to import and use only the parts you need.

• ⬇️ 30%+ smaller download size
• ⬇️ 50%+ smaller parse size
• ⬇️ 60%+ smaller core CSS + smaller external animation files

👷 Better developer experience

There is now a DEV-only messaging system to help you when things go wrong.

🔥 Animation improvements

There is a new /animations folder (like /themes) and creating custom animations is a smoother experience. Additionally, there is new documentation about fully dynamic transitions of a tippy element's dimensions, and work is being done to create an official API for it.

🤩 Plenty of new features

• 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)

🔌 Plugins API

Allows you to extend functionality of tippy instances and create your own props.

♿ Improved accessibility out of the box

Interactive tippys are now accessible by default, and DEV warnings will let you know if there is an accessibility problem.

🐞 Subtle behavioral bugs fixed and improvements made

• animateFill: true is no longer default, so the shape cut off issue is not present with large content unless you intentionally use it
• hideOnClick uses mousedown instead of click
• Calling .disable() will hide an instance if it's currently visible
• Updating content while hovering over an interactive element will not break the mouseleave to hide it
• For instances with a delay, if the tippy began to transitioning out and the instance was triggered again before unmounting, it will ignore the delay
• Window blur listener will only blur references whose tippy is not visible upon blur
• If using multiple tippys on a single element, screenreaders will now announce all of them
• In touch and keyboard contexts, delay is always 0

Installation

Package Managers:

# npm
npm i tippy.js@5

# Yarn
yarn add tippy.js@5

CDN:

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

Fixes

• 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
• Fix #532: Add referenceNode property for followCursor (NOTE: awaiting popper.js@1.16.0 release)

Fixes

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

Fixes

• Mounting behavior (IE11 scrollbar flicker) (#509)
• 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 (#504)

Fixes

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

Features

• Added triggerTarget option to apply the trigger listeners to a different node from the positioning reference
• Added onTrigger option to allow calls to .set() to change the reference position and instance props based on the event before the tooltip is shown without interrupting the lifecycle (unlike wait)
• Added ability to pass a ReferenceElement to HideAllOptions.exclude for references with multiple tippys

Fixes

• Make tippy.group() and updateDuration updateable
• Fix when popperOptions.onCreate and popperOptions.onUpdate are called so they match the actual invocations by Popper.js
• Fix followCursor not respecting popperOptions.modifiers.preventOverflow.padding
• Fix multiple tippys from only displaying one if using touch and hideOnClick: true
• Fix the tooltip moving with the cursor if over the popper element when using followCursor: '{horizontal, vertical}' and interactive: true
• [TypeScript] Fix instance.reference type to account for VirtualReference

Fixes

• Change show checks to fix Shadow DOM support (#453)
• Change notransition technique (#454)
• Add x-out-of-boundaries attribute to tooltip node (#455)
• Optimize set(): avoid recreating popperInstance by comparing props (#456)
• Remove tap highlight color by default on iOS

Features

• Add x-placement attribute to tooltip node, allowing you to style without needing to use the .tippy-popper selector

Example

Before:

.tippy-popper[x-placement^='top'] .tippy-tooltip.my-theme .tippy-arrow {
  border-top-color: pink;
}

After:

.tippy-tooltip.my-theme[x-placement^='top'] .tippy-arrow {
  border-top-color: pink;
}

Fixes

• Apply correct mutations when calling .set() with a popperInstance dependency update

This release mainly fixes some minor CSS issues

Fixes

• Make rem units align with whole pixels using 16px base default
• Size round arrow closer to default sharp arrow so it reaches the edges of the popper + reduce arrow margins overall
• Fix infinite loop when popperOptions is undefined instead of an object
• Fix small gaps when using the round arrow in Edge/IE11
• Fix longstanding issue (since v0) of Popper's preventOverflow not taking into account the distance prop

Fixes

• Fix UC Browser support: animateFill being broken, and onShown / onHidden not being called (#427)
• Fix distance option when setting it as a default (#429)
• Fix edge case error if no nodes are in <head> when injecting CSS

Fixes

• Fix content as a function (#424)

Install

npm i tippy.js@latest

Overall minzipped size has been reduced by about 400 bytes

Features / Improvements

• ✅ followCursor: 'initial' works on touch devices too

• ✅ Padding between popper and container/viewport edges has been reduced to 3px from 5px by default

• ✅ scale animation has its transform origin sticking to the reference element

• ✅ tippy.hideAll() method is now actually useful!

It no longer checks hideOnClick unexpectedly. In other words:

tippy.hideAll()

Does exactly what it says. All tippys will be hidden no matter what (using their own specified durations).

There's even options now too, for example, make all of them hide instantly (useful for scrolling):

tippy.hideAll({ duration: 0 })

Or exclude a particular instance from hiding:

tippy.hideAll({ exclude: tippyInstance })

• ✅ tippy.group() method - finally, a built-in solution to #81!

How to use it:

const instances = tippy('button', { delay: 1000 })
tippy.group(instances)

// Optional:
tippy.group(instances, {
  duration: number | [number, number], // instead of 0 between each show,
  delay: number | [number, number], // if you didn't specify a delay in the instances
})

As simple as that, the tooltips will now instantly show when hovering between items in the group instead of waiting for the delay sluggishly.

• ✅ updateDuration option is now 0 instead of 200 by default

Flips don't have the weird transition if using flipOnUpdate: true (note that it's off by default now). Specifying a number now uses true smooth flips, where the popper element smoothly transitions from one placement to another. The effect is quite satisfying.

• ✅ role option - instead of tooltip, certain popovers may need to be menu or dialog for accessibility reasons.

tippy('button', {
  role: 'menu'
})

Breaking changes

• 🔴 You no longer need to import CSS when using modules. It gets injected to the very top of the <head>, like the UMD version.

// v3
import tippy from 'tippy.js'
import 'tippy.js/dist/tippy.css'

// v4
import tippy from 'tippy.js'

Also, files renamed to index instead of tippy.

In case you don't want this, you still can import it separately:

import tippy from 'tippy.js/esm'
import 'tippy.js/index.css'

Additionally, everything exists in the root directory instead of under dist/. For example, themes:

import 'tippy.js/themes/light.css'

Why: cleaner import experience for consumers

• 🔴 popper.js is external in all formats, so no more tippy.standalone. This means CDN includes must reference it separately.

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

Why: to prevent popper.js from becoming outdated and lagging behind popper releases, works like a dependency should

• 🔴 Remove tippy.one(). Instead, an instance will be returned in two cases: if the reference is either an element or a virtual element

// v3
const collection = tippy('.btn')
const collection = tippy(document.querySelector('.btn'))
const instance = tippy.one('.btn')
const instance = tippy.one(document.querySelectorAll('.btn'))

// v4
// Instance
const instance = tippy(document.querySelector('.btn'))
const instance = tippy(virtualElement)
// Instance[]
const instances = tippy('#btn')
const instances = tippy('.btn')
const instances = tippy(document.querySelectorAll('.btn'))

Why: collections are not useful and don't need to exist. But we want to avoid an opaque return value if using a certain type. Therefore even if only a single element is given an instance when using a CSS selector, it always returns an array.

• 🔴 Remove tippy.useCapture() and tippy.disableAnimations()

Why: .useCapture() is now default in v3 anyway. .disableAnimations() was for testing environments however the new delay value causes async behavior when hiding. In testing environments, use the following call to make everything synchronous:

tippy.setDefaults({ duration: 0, delay: 0 })

• 🔴 Remove arrowTransform option

Why: Since introducing a bordered theme (light-border), using transforms distorts the shape of the arrow border. Arrow transforms should be specified in CSS using a theme.

• 🔴 Remove autoFocus and shouldPopperHideOnBlur options. Remove all focus handling and leave it up to the developer.

Why: The recommended accessible popover is to append it directly after the reference element which requires no focus handling. This will ensure focusable elements inside the tippy can be tabbed to afterwards. Sometimes this can be problematic though, with regards to z-index /stacking issues and the popover needs to be appended to the body. In this case it's up to the developer to create modal-like behavior with a close button and focus trapping, they can programmatically call .focus() where need be.

• 🔴 The AJAX image example (smooth transition): you must explicitly define transition styles on the tooltip now.

e.g. in the onShow() lifecycle:

onShow(instance) {
  const { tooltip } = instance.popperChildren
  tooltip.style.transitionDuration = '0.2s'
  tooltip.style.transitionProperty = 'visibility, opacity, height'
}

• ⚠️ Rename performance to ignoreAttributes

Why: ignoreAttributes describes what it's doing, performance described the side effect of doing it

• ⚠️ Rename tippy.hideAllPoppers() to tippy.hideAll()

Why: Shorter and more concise and conveys the same meaning

• ⚠️ In event delegation mode, content and appendTo as functions receive the target element rather than the delegate reference

Why: It's actually useful this way

• ⚠️ Rename livePlacement to flipOnUpdate, with much better behavior. It's now false by default. The tippy will still update its position on scroll, but flipping while scrolling/resizing, etc is disabled by default.

Why: Better UX (subjective) to keep the placement static after showing and prevent flips while scrolling

• ⚠️ If your content is an element, and you change elements inside it, you must call instance.popperInstance.scheduleUpdate().

Why: MutationObserver is not as robust as a ResizeObserver and has been removed. If you want complete accuracy consider using a polyfill for ResizeObserver.

• ⚠️ Opinioned CSS like font-smoothing has been removed. Tippy elements should inherit the global styles as much as possible.

Why: Let the developer have more control and not introduce unexpected styling

Fixes

• Fix for tippys with delays when leaving the popper, it sometimes would not close

• Correctly parse null in attributes

Install

npm i tippy.js@next

Overall minzipped size has been reduced by about 400 bytes

Breaking changes

• 🔴 You no longer need to import CSS when using modules. It gets injected to the very top of the <head>, like the UMD version.

// v3
import tippy from 'tippy.js'
import 'tippy.js/dist/tippy.css'

// v4
import tippy from 'tippy.js'

Also, files renamed to index instead of tippy.

In case you don't want this, you still can import it separately:

import tippy from 'tippy.js/esm'
import 'tippy.js/index.css'

Additionally, everything exists in the root directory instead of under dist/. For example, themes:

import 'tippy.js/themes/light.css'

Why: cleaner import experience for consumers

• 🔴 popper.js is external in all formats, so no more tippy.standalone. This means CDN includes must reference it separately.

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

Why: to prevent popper.js from becoming outdated and lagging behind popper releases, works like a dependency should

• 🔴 Remove tippy.one(). Instead, an instance will be returned in two cases: if the reference is either an element or a virtual element

// v3
const collection = tippy('.btn')
const collection = tippy(document.querySelector('.btn'))
const instance = tippy.one('.btn')
const instance = tippy.one(document.querySelectorAll('.btn'))

// v4
// Instance
const instance = tippy(document.querySelector('.btn'))
const instance = tippy(virtualElement)
// Instance[]
const instances = tippy('#btn')
const instances = tippy('.btn')
const instances = tippy(document.querySelectorAll('.btn'))

Why: collections are not useful and don't need to exist. But we want to avoid an opaque return value if using a certain type. Therefore even if only a single element is given an instance when using a CSS selector, it always returns an array.

• 🔴 Remove tippy.useCapture() and tippy.disableAnimations()

Why: .useCapture() is now default in v3 anyway. .disableAnimations() was for testing environments however the new delay value causes async behavior when hiding. In testing environments, use the following call to make everything synchronous:

tippy.setDefaults({ duration: 0, delay: 0 })

• 🔴 Remove arrowTransform option

Why: Since introducing a bordered theme (light-border), using transforms distorts the shape of the arrow border. Arrow transforms should be specified in CSS using a theme.

• 🔴 Remove autoFocus and shouldPopperHideOnBlur options. Remove all focus handling and leave it up to the developer.

Why: The recommended accessible popover is to append it directly after the reference element which requires no focus handling. This will ensure focusable elements inside the tippy can be tabbed to afterwards. Sometimes this can be problematic though, with regards to z-index /stacking issues and the popover needs to be appended to the body. In this case it's up to the developer to create modal-like behavior with a close button and focus trapping, they can programmatically call .focus() where need be.

• ⚠️ Rename performance to ignoreAttributes

Why: ignoreAttributes describes what it's doing, performance described the side effect of doing it

• ⚠️ Rename tippy.hideAllPoppers() to tippy.hideAll()

Why: Shorter and more concise and conveys the same meaning

• ⚠️ In event delegation mode, content and appendTo as functions receive the target element rather than the delegate reference

Why: It's actually useful this way

• ⚠️ Rename livePlacement to flipScroll, with much better behavior. It's now false by default. The tippy will still update its position on scroll, but flipping while scrolling is disabled.

Why: Better UX (subjective) to keep the placement static after showing and prevent flips while scrolling

• ⚠️ If your content is an element, and you change elements inside it, you must call instance.popperInstance.scheduleUpdate().

Why: MutationObserver is not as robust as a ResizeObserver and has been removed. If you want complete accuracy consider using a polyfill for ResizeObserver.

• ⚠️ Opinioned CSS like font-smoothing has been removed. Tippy elements should inherit the global styles as much as possible.

Why: Let the developer have more control and not introduce unexpected styling

Features / Improvements

• ✅ followCursor: 'initial' works on touch devices too

• ✅ updateDuration option is now 0 instead of 200 by default

Flips don't have the weird transition if using flipScroll: true (note that it's off by default now). Specifying a number now uses true smooth flips, where the popper element smoothly transitions from one placement to another. The effect is quite satisfying.

• ✅ Padding between popper and container/viewport edges has been reduced to 2px from 5px by default

• ✅ scale animation has its transform origin sticking to the reference element

• ✅ tippy.hideAll() method is now actually useful!

It no longer checks hideOnClick unexpectedly. In other words:

tippy.hideAll()

Does exactly what it says. All tippys will be hidden no matter what (using their own specified durations).

There's even options now too, for example, make all of them hide instantly (useful for scrolling):

tippy.hideAll({ duration: 0 })

Or exclude a particular instance from hiding:

tippy.hideAll({ exclude: tippyInstance })

• ✅ tippy.group() method - finally, a built-in solution to #81!

How to use it:

const instances = tippy('button', { delay: 1000 })
tippy.group(instances)

// Optional:
tippy.group(instances, {
  duration: number | [number, number], // instead of 0 between each show,
  delay: number | [number, number], // if you didn't specify a delay in the instances
})

As simple as that, the tooltips will now instantly show when hovering between items in the group instead of waiting for the delay sluggishly.

• ✅ role option - instead of tooltip, certain popovers may need to be menu or dialog for accessibility reasons.

tippy('button', {
  role: 'menu'
})

Fixes

• Make touchstart passive for touchHold: true listeners (#344)
• Ability to specify null / false for the aria option to disable the attribute completely (#402)
• Improved inertia animation a bit
• followCursor: 'initial' edge case fix with delays

Features

• Add followCursor: 'initial' option (#374)
• Add boundary option (#394)
• autoFocus and aria options (#393)

Fixes

• Typings improvements (#395)

Features

• Reintroduce maxWidth option

Fixes

• popper.js^1.14.6 includes position rounding fixes
• Fix slight text blurriness on Safari when animateFill: true
• google theme adheres to size option
• Arrow centering fixes for light-border.css due to Popper.js issue

Deprecations

• Deprecate tippy.useCapture() and make capture phase for the global click listener default. This prevents the need to wrap calls to .show() in setTimeout if manually triggering the tooltip after a click event somewhere

Fixes

• Add characterData to the popper mutation observer so changes to textual content within a tippy is detected and its position updated accordingly. Mainly noticeable in React updates.
• Use state.isMounted over state.isVisible to determine if hide(0) should be called when destroying a tippy. This was not a leak but caused glitches when using the React component after changing routes and unmounting the Tippy component.

Fixes

• light-border.css: fix arrow transparency and reduce theme file size
• Make touchstart passive
• Fix tooltip overflowing window edge in followCursor mode
• Reduce tippy.css size a bit

• 🐛 Fix regression with data-tippy-content attribute (#341)

• Include IE11 transitionend fix
• Subtler animations for scale and perspective
• Popper.js 1.14.4
• Include esm directory and module field in package.json

Tippy.js 3: alpha 0

The first alpha release of Tippy.js v3.

npm i tippy.js@next

What's changed?

You no longer use a title attribute on elements, and the html option has been removed. Both functionalities have been streamlined into a single prop: content.

Method 1: Auto

<button data-tippy="Tooltip">Text</button>
<button data-tippy="<strong>HTML</strong>">Text</button>

Elements with a data-tippy attribute are automatically given a tooltip. You no longer need to touch JavaScript. (Note on performance: It takes <0.5ms to do this check on a page if there are no tooltips).

Method 2: content

You can give elements a data-tippy-content attribute and use the function:

<button data-tippy-content="Tooltip">Text</button>
<script>tippy('button')</script>

Or specify the content as an option.

<button>Text</button>
<script>tippy('button', { content: 'Tooltip' })</script>

It can contain HTML, and you can use an HTMLElement as the value.

tippy() call

The object that is returned:

• selector is now named targets
• tooltips is now named instances

Instances

• New popperChildren property: access the children of the popper element easily without needing to do query selections or manual DOM walking.
• options has been renamed to props. Options are the props you supply optionally to tippy(), but it doesn't make sense for the tooltip configuration object to be called options. Instead, it's now props, inspired by React.
• state object properties are all prefixed with is because they are boolean values.
• listeners made private

Methods

The most useful new method is set(). It allows you to update the props of a tooltip after it has been created.

const tip = tippy.one('.btn', { 
  content: 'Hello!', 
  arrow: true,
  delay: 500
})

// Later on...
tip.set({ 
  content: 'Bye!', 
  arrow: false,
  delay: 0
})

Static

• tippy.setDefaults(props) - pass an object in to change the default configuration
• tippy.browser removed

Options/Props

• a11y: true - (accessibility shorthand): ensure the reference element can receive focus
• allowTitleHTML: true is now allowHTML
• hideOnClick changes "persistent" to "toggle" and it has the opposite behavior. This means that hideOnClick: false will prevent click-triggered tooltips from ever hiding unless you specify "toggle". Not 100% sure on this, however.
• touch: true- display the tooltip on touch devices?
• createPopperInstanceOnInit: false is now lazy: true. More concise name.
• showOnInit: false - show the tooltip immediately?
• maxWidth removed. Should be handled by a theme in CSS because of narrow mobile devices.
• multiple: false - can the reference have multiple tippys? Currently each new instance overrides the previous _tippy property. It most likely needs to be turned into an array on the second init, but I fear this causes unpredictable behavior. (The previous option which allowed multiple click triggered tooltips to be open is now gone. I don't see much demand for it, but it might return as a different name).
• duration/delay: you can now leave a value undefined in the array and the default value is used. e.g. duration: [, 100] (use default for show) or duration: [100] (use default for hide). It's more concise than an object: duration: { hide: 100 } but the syntax is kind of messy. Might change this.

Accessibility/focus handling

Focus handling and accessibility has been improved. Tabbing/keyboard nav around interactive tooltips now works better.

Handling fallback for unsupported browsers

I believe this should be handled by the user, not the library.

The best way is to inline the tooltip content next to the reference element on old mobile & desktop browsers for interactive HTML popovers. For simple tooltips on desktop, manually set the title property on the element.

Unsupported = <0.5% worldwide usage or nonstandard browsers.

TODO before final release

• Fix #193
• More configurable animations. Currently can be handled with theme but requires lots of boilerplate selectors. Would be nice to make it declarative as an option.
• #174: Cooler animations someday?
• Finish writing tests. There's over 200, but I probably need to move back to a browser from Jest because there are too many things that need to be tested in a real browser using a layout engine.
• Package: sourcemaps, ES module (maybe, since there's not much to treeshake)

• fix: #249
• fix: remove problematic iOS code that autoclicks which sometimes causes doubles clicks

• fix #224: hotfix for regression due to #221
• fix #221: disabled elements should not show tooltip in FF to align with other browsers
• fix #218: destroying tooltip on click should not throw errors
• fix #216: sticky option positioning issue on FF due to new Popper.js positioning fix

• Upgrade Popper.js dependency: 1.14.1 => 1.14.2which has some nice fixes for positioning and bundle size 😄
• Add new static method: tippy.one() for creating one single tooltip, it will return the tooltip instance directly
• css: remove pointer-events on round arrow SVG if not interactive

fix: remove unnecessary files from npm package (#210)

• Upgrade Popper.js dependency: 1.13.0 => 1.14.1
• Adds tippy.version property to the module, and injects a banner at the top of unminified files
• Better handling of focus/tabbing & interactivity
• fix #207

• Add allowTitleHTML option (#197)
• Add tippy.disableAnimations() to modify defaults to apply no animations to tooltips (mainly for automated testing)
• Tooltip arrow now follows the cursor when it hits the boundaries (#188)
• Improved round arrow SVG shape
• Slightly improved backdrop fill animation

• fix #185: set .tippy-popper line-height to 1.4 to prevent descender letters like "g" and "y" from being cut off depending on the font/browser/OS. Will not affect themes with custom line-heights because of lower specificity.

• fix #181

• Add livePlacement option to prevent flipping on scroll.
• Fix #177, #179

• fix #170 - prevent scroll jumps when focusing interactive tooltips