tippyjs-react

@tippyjs/react is the official React wrapper for Tippy.js, the Popper-powered tooltip, popover, dropdown, and menu library. Instead of reimplementing positioning logic, it forwards nearly all of Tippy.js’s native props straight onto a <Tippy> component, so anything documented for vanilla Tippy.js works unchanged, while adding a small set of React-specific conveniences: a visible prop for fully controlled mode, disabled, className for styled-components/emotion integration, and a reference prop for cases where the trigger element can’t be a direct child.

Beyond the default DOM-rendering mode, the package ships a separate /headless entry point that hands rendering control back to the consumer via a render prop, and a useSingleton() hook that ports Tippy.js’s createSingleton addon into idiomatic React so many trigger elements can share one popper instance. Internally it manages instance lifecycle with layout effects and a mutable ref “box” rather than component state, mounting content through a React portal so JSX content composes naturally with tippy.js’s imperative DOM positioning.

What You Get

• A <Tippy> component that accepts all native Tippy.js props plus visible, disabled, className, and reference for React-specific control
• A /headless import variant that renders your own markup via a render prop instead of Tippy.js’s default DOM/CSS
• A useSingleton() hook that ports the createSingleton addon into React, letting many trigger elements share one popper instance
• Controlled mode via the visible prop, bypassing native trigger/hideOnClick handling for fully React-driven show/hide state
• TypeScript type definitions (index.d.ts) covering the component, headless render signature, and singleton hook

Common Use Cases

• Adding lightweight tooltips to icon buttons or truncated text without hand-rolling positioning math
• Building custom-styled popovers and dropdown menus with styled-components or emotion via the className prop or headless render mode
• Driving many tooltips from one shared instance (e.g. a table with a tooltip per row) using useSingleton() to cut DOM/instance overhead
• Fully controlled tooltips whose visibility is driven by external React state rather than hover/click triggers
• Animating tooltip/popover entry and exit with framer-motion or react-spring through the headless render prop

Under The Hood

Architecture The library is built as a generator/factory pattern: TippyGenerator(tippy) in src/Tippy.js and useSingletonGenerator(createSingleton) in src/useSingleton.js both take the underlying tippy.js core function as an argument and return the actual React component/hook, which lets src/index.js (default DOM mode) and src/headless.js (headless mode) share the same logic while injecting a different rendering strategy. Instance lifecycle is handled through useIsomorphicLayoutEffect (SSR-safe layout effect from util-hooks.js): a create effect instantiates the tippy instance against a detached container div on mount and destroys it on unmount, while a separate update effect diffs incoming props against the live instance via deepPreserveProps (in utils.js) and calls instance.setProps/show/hide as needed. Imperative state (the container div, the tippy instance, render counts) is kept in a ref-backed “mutable box” rather than component state to avoid unnecessary re-renders, and content is delivered into that container through a React portal, letting arbitrary JSX compose with tippy.js’s own imperative DOM positioning without React and Tippy.js fighting over the same nodes.

Tech Stack Runtime dependencies are minimal: tippy.js ^6.3.1 (itself built on Popper) is the only production dependency, with react/react-dom >=16.8 declared as peer dependencies since the library relies entirely on hooks. The package is built with Rollup (rollup.config.js) into UMD and ESM bundles plus a minified unpkg build, transpiled via Babel (preset-env, preset-react, and babel-plugin-annotate-pure-calls for tree-shake-friendly output); Parcel is used only to serve the local demo/ app during development. Type definitions are hand-authored in a plain index.d.ts rather than compiled from TypeScript source.

Code Quality Tests run under Jest with @testing-library/react and fake timers, covering the core <Tippy> component, useSingleton(), and the utility functions, with matching Jest snapshots checked in under test/__snapshots__/. Linting is configured via ESLint (eslint:recommended plus plugin:react/recommended and react-hooks) with Prettier enforced through a Husky pre-commit hook and lint-staged, and a .travis.yml config is present though the project’s own commit history shows infrequent recent activity. There is no TypeScript source, so type safety is limited to the ambient declaration file rather than compiler-checked implementation code; dev-mode console.warn/console.error guards catch a handful of common misuse patterns (e.g. mixing visible with native trigger props).

API Design The public API is deliberately thin: a single <Tippy content="..."> wrapper forwards essentially the entire native Tippy.js prop surface untouched, so anything documented for vanilla Tippy.js keeps working with no separate abstraction layer to learn, while only four React-specific props (visible, disabled, className, reference) are layered on top. useSingleton() maps the imperative createSingleton addon onto an idiomatic two-value hook return ([source, target]), and the separate /headless entry point offers a clean render-prop escape hatch for full markup control at the cost of a second import path and some mode-specific branching (headless plus singleton composition has a few documented sharp edges around attribute ordering).