Skip to content
Tippy Logo

Tippy.js

View on GitHub
Currently v6.2.7

All Props

"Props" are configurable properties you can pass optionally to the tippy() constructor.

tippy(targets, { // props });

#allowHTML Configured by the render() function

Determines if content strings are parsed as HTML instead of text.

Warning

Make sure you are sanitizing any user data if rendering HTML to prevent XSS attacks.

tippy(targets, { // default allowHTML: false, // parse `content` strings as HTML allowHTML: true, });

#animateFill Configured by the render() functionRequires importing its plugin when using modules

Determines if the background fill color of the tippy should be animated.

tippy(targets, { // default animateFill: false, // enable it animateFill: true, });

Plugin

When using modules (esm), you must import this plugin to use it.

You must also import the dist/backdrop.css & animations/shift-away.css stylesheets for styling to work.

import tippy, {animateFill} from 'tippy.js'; import 'tippy.js/dist/backdrop.css'; import 'tippy.js/animations/shift-away.css'; tippy(targets, { animateFill: true, plugins: [animateFill], });

#animation Configured by the render() function

The type of transition animation. See Animations for details.

tippy(targets, { // default animation: 'fade', });

Note

This is false by default when using Headless Tippy.


#appendTo

The element to append the tippy to. If interactive: true, the default behavior is appendTo: "parent". See Accessibility for more information.

Sometimes the tippy needs to be appended to a different DOM context due to accessibility, clipping, or z-index issues.

tippy(targets, { // default (takes reference as an argument) appendTo: () => document.body, // append to reference's parentNode appendTo: 'parent', // append to an Element appendTo: element, });

#aria

The aria attribute configuration. Both properties are optional:

  • content: The aria-* attribute applied to the reference element to announce the tippy content.
  • expanded: Whether to add an aria-expanded attribute to the reference element.
tippy(targets, { // default aria: { // `null` when interactive: true, otherwise "describedby" content: 'auto', // matches `interactive` boolean expanded: 'auto', }, // announce as a label rather than a description // the content will also be announced with `interactive: true` aria: { content: 'labelledby', }, // to abide by strict WCAG 2.1 rules with `interactive: true` to make it // hoverable if it's not actually interactive, but the content will still be // announced aria: { content: 'describedby', }, // disable completely, left up to you to control aria: { content: null, expanded: false, }, });

#arrow Configured by the render() function

Determines if the tippy has an arrow.

tippy(targets, { // default arrow: true, // disable arrow arrow: false, // custom arrow string arrow: '<svg>...</svg>', // custom arrow element arrow: svgElement, });

Warning

A string is parsed as .innerHTML. Don't pass unknown user data to this prop.

Note

To use the default round arrow, import roundArrow from the package (tippy.roundArrow in the umd version) and pass it as the value.

You must also import dist/svg-arrow.css when using SVG arrows for styling to work.

import tippy, {roundArrow} from 'tippy.js'; import 'tippy.js/dist/svg-arrow.css'; tippy(targets, { arrow: roundArrow, });

#content Configured by the render() function

The content of the tippy.

tippy(targets, { // default content: '', // string content: 'Hello', // Element content: document.createElement('div'), // (reference) => string | Element content: (reference) => reference.getAttribute('title'), });

Note

To render strings as HTML, set allowHTML: true. This can open you up to XSS attacks, so be careful.


#delay

Delay in ms once a trigger event is fired before a tippy shows or hides.

tippy(targets, { // default delay: 0, // show and hide delay are 100ms delay: 100, // show delay is 100ms, hide delay is 200ms delay: [100, 200], // show delay is 100ms, hide delay is the default delay: [100, null], });

#duration Configured by the render() function

Duration in ms of the transition animation.

tippy(targets, { // default duration: [300, 250], // show and hide durations are 100ms duration: 100, // show duration is 100ms, hide duration is 200ms duration: [100, 200], // show duration is 100ms, hide duration is the default duration: [100, null], });

#followCursor Requires importing its plugin when using modules

Determines if the tippy follows the user's mouse cursor.

tippy(targets, { // default followCursor: false, // follow on both x and y axes followCursor: true, // follow on x axis followCursor: 'horizontal', // follow on y axis followCursor: 'vertical', // follow until it shows (taking into account `delay`) followCursor: 'initial', });

Plugin

When using modules (esm), you must import this plugin to use it.

import tippy, {followCursor} from 'tippy.js'; tippy(targets, { followCursor: true, plugins: [followCursor], });

#getReferenceClientRect

Used as the positioning reference for the tippy.

tippy(targets, { // default (uses the reference passed as first argument) getReferenceClientRect: null, // function that returns a ClientRect object getReferenceClientRect: () => ({ width: 100, height: 100, left: 100, right: 200, top: 100, bottom: 200, }), });

#hideOnClick

Determines if the tippy hides upon clicking the reference or outside of the tippy. The behavior can depend upon the trigger events used.

tippy(targets, { // default hideOnClick: true, // never hide upon clicking hideOnClick: false, // hide only upon clicking the reference, but not outside hideOnClick: 'toggle', });

hideOnClick: true with click:

hideOnClick: "toggle" with click:

hideOnClick: false with mouseenter (a click trigger will never hide):


#ignoreAttributes

When using UI (component) libraries like React, this is generally not necessary and slows down initialization perf a bit.

tippy(targets, { // default ignoreAttributes: false, // don't consider `data-tippy-*` attributes on the reference element ignoreAttributes: true, });

#inertia Configured by the render() function

Determines if a (customizable) CSS spring-like animation is applied to the transition animation.

Changing the show duration to a higher value makes this look better.

tippy(targets, { // default inertia: false, // enable it inertia: true, });
.tippy-box[data-inertia][data-state='visible'] { transition-timing-function: cubic-bezier(...); }

#inlinePositioning Requires importing its plugin when using modules

Provides enhanced support for display: inline elements. It will choose the most appropriate rect based on the placement.

tippy(targets, { // default inlinePositioning: false, // enable it inlinePositioning: true, });

Plugin

When using modules (esm), you must import this plugin to use it.

import tippy, {inlinePositioning} from 'tippy.js'; tippy(targets, { inlinePositioning: true, plugins: [inlinePositioning], });

#interactive

Determines if the tippy has interactive content inside of it, so that it can be hovered over and clicked inside without hiding.

tippy(targets, { // default interactive: false, // enable it interactive: true, });

#interactiveBorder

Determines the size of the invisible border around the tippy that will prevent it from hiding if the cursor left it.

tippy(targets, { // default interactiveBorder: 2, // 30px interactiveBorder: 30, });

#interactiveDebounce

Determines the time in ms to debounce the interactive hide handler when the cursor leaves the tippy's interactive region.

Offers a temporal (rather than spacial) alternative to interactiveBorder, although it can be used in conjunction with it.

tippy(targets, { // default interactiveDebounce: 0, // 75ms interactiveDebounce: 75, });

#maxWidth Configured by the render() function

Specifies the maximum width of the tippy. Useful to prevent it from being too horizontally wide to read.

Note

This is applied to the .tippy-box (inner element), rather than the root positioned popper node. The core CSS applies max-width: calc(100vw - 10px) on the root popper node to prevent it from exceeding the viewport width on small screens.

tippy(targets, { // default maxWidth: 350, // no maxWidth maxWidth: 'none', });

#moveTransition

Specifies the transition applied to the root positioned popper node. This describes the transition between "moves" (or position updates) of the popper element when it e.g. flips or changes target location.

tippy(targets, { // default moveTransition: '', // custom transition moveTransition: 'transform 0.2s ease-out', });

#offset

Displaces the tippy from its reference element in pixels (skidding and distance).

See Popper's docs for details.

tippy(targets, { // default [skidding, distance] offset: [0, 10], });

#onAfterUpdate

Invoked after the tippy has been updated (via .setProps()).

tippy(targets, { onAfterUpdate(instance, partialProps) { // ... }, });

#onBeforeUpdate

Invoked before the tippy has been updated (via .setProps()).

tippy(targets, { onBeforeUpdate(instance, partialProps) { // ... }, });

#onClickOutside

Invoked when the user clicks anywhere outside of the tippy or reference element.

tippy(targets, { onClickOutside(instance, event) { // ... }, });

#onCreate

Invoked once the tippy has been created.

tippy(targets, { onCreate(instance) { // ... }, });

#onDestroy

Invoked once the tippy has been destroyed.

tippy(targets, { onDestroy(instance) { // ... }, });

#onHidden

Invoked once the tippy has been fully hidden and unmounted from the DOM.

tippy(targets, { onHidden(instance) { // ... }, });

#onHide

Invoked once the tippy begins to hide.

tippy(targets, { onHide(instance) { // ... }, });

You can optionally return false from this lifecycle to cancel a hide based on a condition.


#onMount

Invoked once the tippy has been mounted to the DOM (and the popperInstance created).

tippy(targets, { onMount(instance) { // ... }, });

#onShow

Invoked once the tippy begins to show.

tippy(targets, { onShow(instance) { // ... }, });

You can optionally return false from this lifecycle to cancel a show based on a condition.


#onShown Configured by the render() function

Invoked once the tippy has been fully transitioned in.

Note

Since this is achieved via CSS transitionend, it relies on your own event listeners if using a custom render function. You'll need to call the lifecycle manually in this case.

tippy(targets, { onShown(instance) { // ... }, });

#onTrigger

Invoked once the tippy has been triggered by a DOM event (e.g. mouseenter).

tippy(targets, { onTrigger(instance, event) { // ... }, });

#onUntrigger

Invoked once the tippy has been untriggered by a DOM event (e.g. mouseleave).

tippy(targets, { onUntrigger(instance, event) { // ... }, });

#placement

The preferred placement of the tippy. Note that Popper's flip modifier can change this to the opposite placement if it has more space.

tippy(targets, { // default placement: 'top', // full list: placement: 'top-start', placement: 'top-end', placement: 'right', placement: 'right-start', placement: 'right-end', placement: 'bottom', placement: 'bottom-start', placement: 'bottom-end', placement: 'left', placement: 'left-start', placement: 'left-end', // choose the side with most space placement: 'auto', placement: 'auto-start', placement: 'auto-end', });

#plugins

Plugins to use. See Plugins for details.

Note

If using tippy.setDefaultProps(), specifying default plugins causes the default plugins to be merged with plugins specified in tippy() constructor calls.

tippy(targets, { // default plugins: [], });

#popperOptions

Specifies custom Popper options. This gives you full control over the tippy's positioning. See Popper's docs for details.

tippy(targets, { // default popperOptions: {}, // detailed example popperOptions: { strategy: 'fixed', modifiers: [ { name: 'flip', options: { fallbackPlacements: ['bottom', 'right'], }, }, { name: 'preventOverflow', options: { altAxis: true, tether: false, }, }, ], }, });

#render

Specifies a custom render function to use. This allows you to create your own tippy element DOM from scratch. Note that all render (R) related props are entirely controlled by you when specifying a custom function.

See Headless Tippy for details.


#role Configured by the render() function

Specifies the role attribute on the tippy element.

tippy(targets, { // default role: 'tooltip', });

#showOnCreate

Determines if the tippy is shown once it gets created, respecting delay.

tippy(targets, { // default showOnCreate: false, // enable it showOnCreate: true, });

#sticky Requires importing its plugin when using modules

Determines if the tippy sticks to the reference element while it is mounted. This is usually not needed, but is useful if the reference element's position is animating, or to automatically update the tippy position without needing to manually do it in certain cases where the DOM layout changes.

Note

This has a performance cost since checks are run on every animation frame. Use this only when necessary!

tippy(targets, { // default sticky: false, // enable it sticky: true, // only check the "reference" rect for changes sticky: 'reference', // only check the "popper" rect for changes sticky: 'popper', });

Plugin

When using modules (esm), you must import this plugin to use it.

import tippy, {sticky} from 'tippy.js'; tippy(targets, { sticky: true, plugins: [sticky], });

#theme Configured by the render() function

Determines the theme of the tippy element. The core CSS defaults to a dark #333 theme. This can be overridden by a custom theme. See Themes for details.

tippy(targets, { // default theme: '', // custom theme theme: 'tomato', });

#touch

Determines the behavior on touch devices.

tippy(targets, { // default touch: true, // disable tippy from showing on touch devices touch: false, // require pressing & holding the screen to show it touch: 'hold', // same as above, but long-press behavior touch: ['hold', 500], });

#trigger

Determines the events that cause the tippy to show. Multiple event names are separated by spaces.

tippy(targets, { // default trigger: 'mouseenter focus', // others: trigger: 'click', trigger: 'focusin', trigger: 'mouseenter click', // only programmatically trigger it trigger: 'manual', });

#triggerTarget

The element(s) that the trigger event listeners are added to. Allows you to separate the tippy's positioning from its trigger source.

tippy(targets, { // default (reference is used) triggerTarget: null, // Element triggerTarget: someElement, // Element[] triggerTarget: [someElement1, someElement2], });

#zIndex

Specifies the z-index CSS on the root popper node.

tippy(targets, { // default zIndex: 9999, });
CustomizationHTML Content

© 2020 — MIT License

Icons made by Freepik from www.flaticon.com