Skip to content
Tippy Logo

Tippy.js

View on GitHub
v6.3.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.

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 trigger: "click":

hideOnClick: "toggle" with trigger: "click":

hideOnClick: false with trigger: "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,
});

Note

When true, the tippy will be appended to the targets parent element for accessibility reasons by default. This means it can inherit styling, such as text-align: center. If you are experiencing issues with positioning, add appendTo: () => document.body to your props.

#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.

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

Note

If the viewport's width is smaller than maxWidth, tippy's core CSS ensures the tippy remains smaller than the screen.

#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

© 2022 — MIT License

Icons made by Freepik from www.flaticon.com