Tippy.js

v6.3.7

Addons

Addons are external functions that control or create many different Tippy instances, and can be tree-shaken away by bundlers.

#Singleton

A singleton is a single tippy element that takes the place of an array of regular tippy instances.

This allows two things:

Smooth transitions of the tippy between many different reference element targets
Elements with tooltips next to each other that have a delay can be "grouped" so they appear to share a timeout, which greatly improves UX

See the demo for it in action.

#Usage

Pass an array of tippy instances to the createSingleton addon function, and a delay prop:

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

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

In the CDN (umd) version, it's available as tippy.createSingleton().

#Overrides

You may want the singleton instance to have some of its props overridden by the individual tippy instances. For example the placement or theme if you'd like to reuse the singleton globally throughout many parts of the application.

You can do this by specifying the prop keys as an array with overrides:

createSingleton(tippyInstances, {
  placement: 'right',
  theme: 'spaceship',
  // The props in the current `tippyInstance` will override the ones above
  overrides: ['placement', 'theme'],
});

#Smooth transitions

Utilize the moveTransition prop, which is the transition between moves (position updates) of the tippy element:

const singleton = createSingleton(tippyInstances, {
  delay: 1000,
  moveTransition: 'transform 0.2s ease-out',
});

#Showing specific tippy instance

The .show() method of singleton accepts an additional parameter:

// Show first child tippy instance if no parameter given
singleton.show();

// Show given child tippy instance
singleton.show(tippyInstances[1]);

// Show child tippy instance related to given reference element
singleton.show(document.querySelector('button'));

// Show child tippy instance at given index
singleton.show(2); // i.e equivalent to passing tippyInstances[2]

#Show instances in order

The .showNext() and showPrevious() methods allow you to loop through and show the child tippy instances in forward or reverse order respectively, relative to tippyInstances array given in createSingleton

// if no child tippy is shown, show first one, otherwise show the next one
singleton.showNext();

// if no child tippy is shown, show last one, otherwise show the previous one
singleton.showPrevious();

Both methods will loop to the other end, like pac-man

singleton.show(0); // show first
singleton.showPrevious(); // loops back and shows last item
singleton.showNext(); // loops to the front and shows first item

#Update

You can update the singleton's instances with the .setInstances() method:

singleton.setInstances(newTippyInstances);

#Destroy

When you call singleton.destroy(), the tippyInstances you passed as an argument will not be destroyed also. They are separate instances that can be reused again elsewhere. You should also destroy the tippy instances upon cleanup.

#Event delegation

Event delegation allows you to let a common parent element handle the creation of tippy instances for child elements.

This allows two things:

It prevents the need to create new instances for new child elements appended to the parent.
It improves performance as the creation of the tippy instances is deferred until they are triggered for the first time.

#Usage

Your markup should have a structure like this example:

<div class="parent">
  <button class="child">Text</button>
  <button class="child">Text</button>
  <button class="child">Text</button>
</div>

Pass a targets argument to the delegate() addon function (the same type the tippy() function can accept) which represents the parent element(s) that should act as a delegate, and a target prop representing a CSS selector that should match the child elements which should receive a tippy.

import {delegate} from 'tippy.js';

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

In the CDN (umd) version, it's available as tippy.delegate()

#Return type

Because delegate() can create many different instances, it returns an opaque value depending on the type supplied, just like tippy().

const delegateInstances = delegate('.parent', {
  target: '.child',
}); // Instance[]

const delegateInstance = delegate(parentElement, {
  target: '.child',
}); // Instance

#Cleanup

By default, when you destroy a delegate instance, it also destroys any child instances that may have been created by it. If you want to prevent this behavior, pass false as an argument:

const delegateInstance = delegate(parentElement, {
  target: '.child',
});

// Prevents further creation and destroys any created child tippy instances
delegateInstance.destroy();
// Prevents further creation only
delegateInstance.destroy(false);

#Polyfill

This addon uses Element.prototype.closest(), which is not supported in older browsers. You will need to polyfill this method to get full support.

Accessibility Plugins