Skip to content

Latest commit

 

History

History
245 lines (176 loc) · 7.96 KB

README.md

File metadata and controls

245 lines (176 loc) · 7.96 KB
Raw

Tippy.js

Build Status npm Downloads gzip Size CDNJS

Tippy.js is a highly customizable vanilla JS tooltip/popover library powered by Popper.js.

Demo and documentation

https://atomiks.github.io/tippyjs/

Installation

npm install tippy.js

CDN: https://unpkg.com/tippy.js/dist/

Basic usage

1. Give elements a title attribute containing the tooltip content.

<button title="Tooltip">Text</button>
<button title="Another tooltip">Text</button>

2. Include the tippy.all.min.js script in your document, which automatically injects Tippy's CSS into head.

Use the full version link! Visit the link in src below to get the latest version.

<script src="https://unpkg.com/tippy.js/dist/tippy.all.min.js"></script>

3. Now call tippy() with a CSS selector to give them a nice tooltip!

<script>
  tippy('button')
</script>

Basic example

<!DOCTYPE html>
<html>
<head><title>Tippy Example</title></head>
<body>
  <!-- Elements with `title` attributes -->
  <button title="Tooltip">Text</button>
  <button title="Another tooltip">Text</button>

  <!-- Include Tippy -->
  <script src="https://unpkg.com/tippy.js/dist/tippy.all.min.js"></script>
  <!-- Initialize tooltips by calling the `tippy` function with a CSS selector -->
  <script>
    tippy('button')
  </script>
</body>
</html>

View the docs for details on all of the options you can supply to customize tooltips to suit your needs.

API

tippy(reference [, options]) => collection object

tippy.one(reference [, options]) => Tippy instance (v2.5+)

reference can be:

  • CSS selector string
  • DOM element (HTMLElement, SVGElement)
  • Array of DOM elements
  • NodeList
  • Object (virtual reference)

Options

tippy(reference, {
  // Available v2.3+ - If true, HTML can be injected in the title attribute
  allowTitleHTML: true,

  // If true, the tooltip's background fill will be animated (material effect)
  animateFill: true,

  // The type of animation to use
  animation: 'shift-away', // 'shift-toward', 'fade', 'scale', 'perspective'

  // Which element to append the tooltip to
  appendTo: document.body, // Element or Function that returns an element

  // Whether to display the arrow. Disables the animateFill option
  arrow: false,

  // Transforms the arrow element to make it larger, wider, skinnier, offset, etc.
  arrowTransform: '', // CSS syntax: 'scaleX(0.5)', 'scale(2)', 'translateX(5px)' etc.

  // The type of arrow. 'sharp' is a triangle and 'round' is an SVG shape
  arrowType: 'sharp', // 'round'

  // The tooltip's Popper instance is not created until it is shown for the first
  // time by default to increase performance
  createPopperInstanceOnInit: false,

  // Delays showing/hiding a tooltip after a trigger event was fired, in ms
  delay: 0, // Number or Array [show, hide] e.g. [100, 500]

  // How far the tooltip is from its reference element in pixels
  distance: 10,

  // The transition duration
  duration: [350, 300], // Number or Array [show, hide]

  // If true, whenever the title attribute on the reference changes, the tooltip
  // will automatically be updated
  dynamicTitle: false,

  // If true, the tooltip will flip (change its placement) if there is not enough
  // room in the viewport to display it
  flip: true,

  // The behavior of flipping. Use an array of placement strings, such as
  // ['right', 'bottom'] for the tooltip to flip to the bottom from the right
  // if there is not enough room
  flipBehavior: 'flip', // 'clockwise', 'counterclockwise', Array

  // Whether to follow the user's mouse cursor or not
  followCursor: false,

  // Upon clicking the reference element, the tooltip will hide.
  // Disable this if you are using it on an input for a focus trigger
  // Use 'persistent' to prevent the tooltip from closing on body OR reference
  // click
  hideOnClick: true, // false, 'persistent'

  // Specifies that the tooltip should have HTML content injected into it.
  // A selector string indicates that a template should be cloned, whereas
  // a DOM element indicates it should be directly appended to the tooltip
  html: false, // 'selector', DOM Element

  // Adds an inertial slingshot effect to the animation. TIP! Use a show duration
  // that is twice as long as hide, such as `duration: [600, 300]`
  inertia: false,

  // If true, the tooltip becomes interactive and won't close when hovered over
  // or clicked
  interactive: false,

  // Specifies the size in pixels of the invisible border around an interactive
  // tooltip that prevents it from closing. Useful to prevent the tooltip
  // from closing from clumsy mouse movements
  interactiveBorder: 2,

  // Available v2.2+ - If false, the tooltip won't update its position (or flip)
  // when scrolling
  livePlacement: true,

  // The maximum width of the tooltip. Add units such as px or rem
  // Avoid exceeding 300px due to mobile devices, or don't specify it at all
  maxWidth: '',

  // If true, multiple tooltips can be on the page when triggered by clicks
  multiple: false,

  // Offsets the tooltip popper in 2 dimensions. Similar to the distance option,
  // but applies to the parent popper element instead of the tooltip
  offset: 0, // '50, 20' = 50px x-axis offset, 20px y-axis offset

  // Callback invoked when the tooltip fully transitions out
  onHidden(instance) {},

  // Callback invoked when the tooltip begins to transition out
  onHide(instance) {},

  // Callback invoked when the tooltip begins to transition in
  onShow(instance) {},

  // Callback invoked when the tooltip has fully transitioned in
  onShown(instance) {},

  // If true, data-tippy-* attributes will be disabled for increased performance
  performance: false,

  // The placement of the tooltip in relation to its reference
  placement: 'top', // 'bottom', 'left', 'right', 'top-start', 'top-end', etc.

  // Popper.js options. Allows more control over tooltip positioning and behavior
  popperOptions: {},

  // The size of the tooltip
  size: 'regular', // 'small', 'large'

  // If true, the tooltip's position will be updated on each animation frame so
  // the tooltip will stick to its reference element if it moves
  sticky: false,

  // Available v2.1+ - CSS selector string used for event delegation
  target: null, // e.g. '.className'

  // The theme, which is applied to the tooltip element as a class name, i.e.
  // 'dark-theme'. Add multiple themes by separating each by a space, such as
  // 'dark custom'
  theme: 'dark',

  // Changes trigger behavior on touch devices. It will change it from a tap
  // to show and a tap off to hide, to a touch-and-hold to show, and a release
  // to hide
  touchHold: false,

  // The events on the reference element which cause the tooltip to show
  trigger: 'mouseenter focus', // 'click', 'manual'

  // Transition duration applied to the Popper element to transition between
  // position updates
  updateDuration: 350,

  // The z-index of the popper
  zIndex: 9999
})

Methods

const instance = tippy.one(reference)
  • instance.show([duration]) - show the tippy, optional duration argument in ms
  • instance.hide([duration]) - hide the tippy, optional duration argument in ms
  • instance.enable() - enable the tippy to allow it to show or hide
  • instance.disable() - disable the tippy to prevent it from showing or hiding
  • instance.destroy() - destroy the tippy, remove listeners and restore title attribute

Component / Library Wrappers