• 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

• #140 - Fix where tooltip with followCursor + delay would not be shown at the correct initial position
• #142 - Add repository field to package.json
• Slightly reduce margins on arrows
• Set tooltips to an empty array upon destroyAll() to free up memory

• Fixes #136
• Fixes error thrown by followCursor option if the tooltip is manually shown
• Prevent CSS from being injected for unsupported browsers

Tippy out of beta!

The full list of changes are described in the first beta notes.

This full release is the same as beta-2 API-wise with a single change to browser.eventsBound as that is intended to be private, it's now browser._eventListenersBound

Bug fixes

• Popper will not overflow the document boundaries on update anymore if the window was resized in a certain way (Popper.js issue since 1.12.5)
• Use clip-path to prevent text from overflowing the backdrop when animating fill if the background is sufficiently different from the text color (no IE/Edge support unfortunately)
• Rare onTransitionEnd() issue with onHidden fixed
• Backdrop transition stutter on Safari fixed finally

Second beta release.

JavaScript

• Added disable() and enable() methods for when you want to temporarily disable a tooltip but not destroy it
• Added a callback hook tippy.browser.onUserInputChange() so you can react to a user's input method change (either mouse or touch). This means you can reliably disable tooltips for touch devices but keep them enabled for mouse if need be.
• Added enabled and visible properties to the Tippy.state object
• Fixed potential issue where the tooltip would remain stuck on the DOM by hiding it instantly on next popper update (i.e. scroll)
• Prevent any tooltip transition when updateDuration: 0 is specified

CSS

• Improved the backdrop fill animation on Safari (but still seems to have issues, just less often..)
• The inertia transition-timing-function has changed to "ease" when it's hiding so it doesn't slingshot back in. To make it look good, use double the duration for show, such as duration: [600, 300]

Tippy 2 Beta 🎉

Tippy just got a whole lot better.

Docs

The docs have been overhauled to display Tippy's features in a more organized fashion.

Package

• src and tests removed from /dist/
• tippy.all.js and tippy.all.min.js are bundled versions of the JS and CSS. The CSS is automatically injected into the document's head, so all that's needed is the script file.

JavaScript

Tippy instances are now single tooltip instances.

New workflow for manual control

const btn = document.querySelector('.btn')
tippy(btn)

// The Tippy instance is now stored on the reference element via `_tippy`. 
// No need to pass any arguments in.
btn._tippy.show()
btn._tippy.hide()

The object returned from tippy() is now different

const tip = tippy('.btn')

tip = {
  selector: '.btn',
  options: { ... },
  tooltips: [Tippy, Tippy, Tippy, ...],
  destroyAll() { ... }
}

Static tippy props/methods

camelCase has been applied to the naming of everything to simplify it.

tippy.Browser is now tippy.browser
tippy.Defaults is now tippy.defaults

tippy.enableDynamicInputDetection (and disable) have been removed. Simply set the property to true or false inside the browser settings.

Identifying Tippy-tooltipped elements

Reference elements now have a data-tippy attribute applied instead of data-tooltipped.

<button title="tooltip" data-tippy>text</button>

Tippy instances

Tippy instances have been simplified.

Properties

• el is now reference

Methods

• show(duration)
• hide(duration)
• destroy()

Removed methods

• update() removed
• getPopperElement() removed
• getReferenceElement() removed
• getReferenceData() removed
• destroyAll() removed

Tippy instances now only need 3 methods: show(), hide(), destroy(), as it only refers to a single tooltip.

show() and hide() only take 1 argument: a custom transition duration, and destroy() needs no arguments.

Data attributes

• data-tippy-* has replaced data-* to prevent conflicts.

Option changes

• position is now placement
• animation has an extra choice: shift-toward. Additionally, shift is now shift-away to better reflect the difference between the two.
• followCursor changed the behavior so that the document is the delegate for mousemove event instead of the reference element itself. This results in smoother behavior.

Removed options

• arrowSize has been replaced by arrowTransform for far greater control over the arrow.
• stickyDuration and flipDuration are now 1 option: updateDuration.

Added options

• createPopperInstanceOnInit - specify whether to create popper instance on init rather than the first show (has a performance impact)
• arrowType - Tippy has a new arrow type – 'Round'. It's a custom SVG shape.
• flip - brings a popperOption to the base-level options
• flipBehavior - brings a popperOption to the base-level options
• maxWidth - specify the max width of the tooltip

CSS

The CSS has been simplified.

Tooltips

Tooltips are smaller by default, including the small and large sizes.

.enter and .leave "global" classes which can cause conflicts have been replaced by [data-state="visible" and [data-state="hidden"].

IDs are now tippy-{id} rather than tippy-tooltip-{id}

Themes

• The light and translucent themes have been removed to simplify the CSS and reduce bundle size. There is now better documentation on creating a theme (mainly for the arrow which is tricky).

Selectors

• [x-arrow] is now .tippy-arrow (triangle) or .tippy-roundarrow (SVG)
• [x-circle] is now .tippy-backdrop
• .html-template is now [data-html]

Misc

• Interactive reference elements now receive .tippy-active instead of just .active to prevent conflicts
• Referect objects are now modified and used as the selector rather than a new object reference

Bug fixes

• Fixed a reflow animation bug on Safari with the backdrop animation.
• Fixed two hide() calls when clicking / touch devices.
• Removed the need for a transitionend timeout.

• Upgrade Popper.js to 1.12.9
• Fix duplicate transitionend listeners added to tooltip

• Fix #118 followCursor - where tooltip would be positioned too far away from cursor/reference if the tooltip was large

• Added ability to pass a custom virtual object instead of a DOM node to act as the positioning reference
• Now catches/silences errors if invalid input argument is passed to tippy constructor

• Improve dynamicTitle option by using a mutation observer instead - #107

• Add option to set html as a function which returns an Element

• Add option to use a NodeList in constructor

• Fix error when in a non-browser environment

• Fix #100 transition issue

Popper.js version updated to 1.12.4

NOTE: There is an issue in Popper 1.12.5 (latest) that affects Tippy too much to use. However it fixed an issue related to fixed containers

Fixes

• appendTo by default is now a function which returns document.body when called (done upon initial tooltip creation), see #95 - particularly useful for Turbolinks when the body element has been changed. This means you can also make appendTo a function which returns an Element.

• Transitions are less glitchy when quickly showing/hiding tooltips

• Tooltips are destroyed upon show if their reference element no longer exists on the DOM

• Popper.js version updated to 1.11.1

Features

• dynamicTitle option (#74)
• Allow an array of elements to be passed in constructor

Fixes

• pointer-events: none added to parent popper element instead of tooltip element - fixes issue (most noticeable in Firefox) with followCursor causing the tooltip to hide when the cursor landed on top of it
• use 20ms time difference instead of 10 for mousemove handler (dynamic input detection) now that Chrome 60 fires 1 per anim frame

• [js] followCursor now respects the offset setting and is more closely positioned to the cursor
• [css] Filling animation improved & arrow margins are 9px for top/bottom and 6px for left/right positions

[fix] #73 - Issue with standalone bundling that was in 1.1.1

Fixes

• fix #72 - blur handler is now bound to the window and will blur tooltipped elements when user leaves the window or tab
• fix #69 - arrows now have 5px margins

Features

• Tooltips now update their position automatically if their content changes (requires window.MutationObserver, so no IE10 support unless polyfilled)

Deprecations

• Callback functions without on prefix are deprecated, prefer onShown, onHidden, etc over shown and hidden - as it better indicates a callback function

Popper.js 1.10.2 => 1.10.6

• fix #65 - only interactive tooltips get a tabindex attribute and it's set to -1 instead of 0
• fix potential iOS problem with mouseenter when the element was not a HTMLElement (like SVG)
• optimize destroyAll() to make it quicker
• add leading hash (#) to DOM elements in the html setting (its data-template-id) so it's consistent with the selector string
• differentiate between instance store and global Store (each instance now has a store property holding all the data objects)
• animateFill made nicer - the content fades out a bit quicker to prevent the text from obviously overflowing (when the background isn't white like the text)
• The popper element uses an easeOutQuart timing function for better transitioning between flips/position updates
• Trying to use update() on a DOM element now throws a warning and aborts as it causes unwanted behavior/data loss

Breaking changes, features and fixes in v1.0.0

Lots of tests have been written (more to be written over time) and code refactored into individual units. API has been simplified.

Core

• Popper.js 1.9.9 => 1.10.2
• The module is now lowercase tippy instead of Tippy as it’s just a factory function not a constructor.
• Access the browser settings set internally by accessing tippy.Browser.
• tippy.defaultSettings => tippy.Defaults
• New dynamic input detection enabled for more reliable settings. Notable settings where this is important is blur listener, followCursor setting and hideOnClick setting.

Settings

• duration and delay can now be either a number or an array for [show, hide].
• hideDelay and hideDuration removed.
• New performance setting added. Disables data-* attribute settings for faster instantiation (around 2x faster).
• theme can now have multiple themes, separate each theme by a space such as theme: 'main light'

Methods

• getTooltippedElement is now getReferenceElement
• getReference is now getReferenceData. It also prefixes private properties with an underscore which are for internal/private use.
• New destroyAll method added. Destroys all tooltips created by the instance.

Callbacks

• beforeHidden is now hide
• beforeShown is now show
• The five are: show, shown, hide, hidden, wait.

Fixes

• Interactive tooltips will now close if the cursor leaves the document and there was no gap between the element, popper and browser window
• Interactive tooltips with delay won't show on first hover if mouseleave was fired before delay finished (#62)
• Enable event listeners for followCursor on touch devices since it doesn’t apply to them.
• closest() changed to a ponyfill instead of a polyfill.
• pointer-events: none added on non-interactive tooltips to prevent cursor from changing and to stop
  hide events from firing when using animation: shift + arrow: true when the cursor lands on the arrow.
• Slightly improved animations
• Simplified simulated click on iOS. External anchor links (i.e. with target="_blank") will require a double-tap, but internal links will load on first tap.
• duration: 0 now makes callbacks synchronous
• outline: 0 added to the popper element
• Pointless/unused CSS removed

• Improved events & UX for iOS: On iOS, like Android, a simulated click event will now be fired along with the mouseenter (iOS stops further events after mouseenter on content change), preventing the need to double-tap buttons with click events and anchor links. Tooltipped anchor links have a click-delay of 300ms to show the tooltip briefly before navigating to the link — however, links with target="_blank" will not navigate due to (presumably) popup blocking with simulated clicks.

• Since Popper.js uses requestAnimationFrame, support is now simply determined like so BROWSER.supported = !!window.requestAnimationFrame, which essentially limits it to ES5-compatible, modernish browsers. caniuse.com shows 94% support– with low Opera Mini usage, it is 96.5% support

• When destroying a tooltip, the element’s original title attribute will be restored

• touchHold setting, which changes the behavior of the mouseenter trigger on touch devices to a touch-and-hold then release, making the tooltip less intrusive

• You can now modify the default settings by accessing the object Tippy.defaultSettings

• Minor, but dispatching simulated events on the document will no longer throw an error

[internal]: private methods moved outside of the class

• [fix] Tooltips work on SVGs again

• [fix] rare cases when tooltip sometimes would not transition due to quick show/hide events in succession

• zIndex setting (#48)
• #18 should be fixed
• transitionFlip replaced with flipDuration resulting in nicer/smoother transitions between flips. Browser window resize now also transitions updates as a result, use 0 to make them instant.
• Minor potentially rare issue with when showing tooltips fixed

• Uses Popper.js 1.9.6 with slight modification to arrow position rounding

• [fix] interactiveBorder logic (was more complicated than I thought) + force close if cursor lands on another different tooltipped element to prevent unwanted overlapping

Features:

interactiveBorder setting - specifies how large the "invisible border" around interactive tooltips is to prevent them from closing. Allows more lenience with the cursor so it doesn't close when it goes slightly off the popper

appendTo setting - allows you to specify where to append the popper instead of document.body

Fixes:

• Fix #46
• this inside callbacks now refers to the actual popper
• Don't assume Tippy is running in browser environment
• Hackish correctTransition function removed and replaced with much better flipping fix