Tippy.js — Tooltip and Popover Library for the Web

Introduction

Tippy.js is a tooltip and popover positioning library that wraps Popper.js (now Floating UI) with a declarative API. It handles placement, flipping, animations, and interactivity out of the box, making it straightforward to add polished tooltips, menus, and dropdowns to any web application.

What Tippy.js Does

• Renders tooltips, popovers, dropdowns, and context menus with smart positioning
• Handles viewport boundary detection and automatic flipping
• Supports HTML content, interactive elements, and nested tippys
• Provides multiple animation styles and custom transition hooks
• Offers a headless mode for unstyled, fully custom rendering

Architecture Overview

Tippy.js creates a wrapper element for each tooltip instance and delegates positioning to Popper.js. The library manages show/hide lifecycle, event listeners, and animation states through an internal state machine. Each instance can be independently configured, updated, or destroyed without affecting others.

Self-Hosting & Configuration

• Install via npm or load from a CDN with the default CSS theme
• Initialize with tippy(selector, options) passing a CSS selector or DOM element
• Set placement, trigger, delay, animation, and theme in the options object
• Use tippy.setDefaultProps() to configure global defaults
• Import additional CSS files for built-in themes like light, material, or translucent

Key Features

• Automatic repositioning when scrolling or resizing the viewport
• Touch device support with configurable touch and hold behavior
• Singleton mode to reuse one tooltip instance across multiple targets
• Event delegation for dynamically added elements
• Accessibility attributes added automatically (aria-describedby, role)

Comparison with Similar Tools

• Floating UI — Lower-level positioning primitive; Tippy.js adds the UI layer on top
• Bootstrap Tooltips — Tied to Bootstrap; Tippy.js is framework-agnostic with richer features
• React Tooltip — React-specific; Tippy.js works with vanilla JS and has a React wrapper (@tippyjs/react)
• Popper.js — Positioning engine only; Tippy.js adds rendering, animations, and lifecycle management

FAQ

Q: Does Tippy.js work with React? A: Yes. Use the official @tippyjs/react package for a component-based API.

Q: Can I put interactive content like buttons inside a tooltip? A: Yes. Set interactive: true to allow users to hover into and interact with the tooltip content.

Q: What is headless mode? A: Headless mode provides positioning logic without any default styles, letting you render completely custom tooltip UI.

Q: How do I handle tooltips on dynamically created elements? A: Use the delegate() add-on to attach tooltips via event delegation on a parent container.

Sources

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