Popover & Tooltip — overview

Why it exists#

tippy.js takes 4,590,050 downloads a week and its repository is archived.

Its most-reacted open issue, #1071 (+32), is "Migrate from Popper (v2) to Floating UI" — the migration that will now never happen. #1183 is "Accessing element.ref was removed in React 19". #1124 is ESM failing under Vitest. #1020 is the dist folder missing from releases. All the marks of an unmaintained package still in four and a half million installs.

Floating UI, at 70 million a week, is excellent and we do not compete with it. It solves where a box goes. It deliberately does not solve what a tooltip is — hover intent, touch, focus, ARIA, dismissal, and the rules about staying open. Everyone who uses it writes that layer themselves, once per project.

The top layer#

The panel uses the browser's own popover API, so it is painted above everything.

That removes two entire categories of bug. There is no z-index in the stylesheet — not a large one, none — because a panel in the top layer cannot be covered. And an anchor inside overflow: hidden — a table cell, a card, a scrolling sidebar — shows its panel in full, because the top layer is not clipped by ancestors.

Tippy's appendTo option exists solely to work around those two problems by moving the element elsewhere in the tree, with everything that then goes wrong about positioning and cleanup. Here there is nothing to move.

The test puts the anchor inside an overflow: hidden box on a page with an element at the maximum z-index, opens the tooltip, and asks the browser what is actually at the panel's centre.

WCAG 2.2 SC 1.4.13#

Content on Hover or Focus has three clauses. Almost nothing implements all three, and each has a test here:

• Dismissible — Escape closes it without moving the pointer, and without the anchor needing focus.
• Hoverable — you can move onto the panel. Going diagonally from the anchor crosses the gap between them, where a naive implementation closes under you; a departure heading towards the panel gets a grace period instead. Tippy needs interactive: true and a plugin for this.
• Persistent — nothing closes on a timer.

And because the rule says hover or focus, a keyboard opens it: focus shows, blur hides.

Touch is not hover#

A phone has no pointer. Pretending it does is why tooltips on phones open and then stick until you tap something unrelated. A long press opens a tooltip, the next tap closes it, and a popover opens on tap.

A tooltip is not a popover#

They get different ARIA — aria-describedby against aria-expanded plus aria-controls — different triggers, different dismissal and different focus behaviour. So they are two functions rather than one with a flag, and the one you called decides what a screen reader is told.

Positioning, at 590 bytes#

Ours, not a dependency: twelve placements, flip when there is no room, slide along the edge to stay on screen, and an arrow placed from the anchor's position rather than the panel's, so a slide leaves it still pointing at the right thing. It is pure arithmetic with no DOM in it, and exported on its own.

It does not try to be Floating UI. There is no autoUpdate with ResizeObserver on every ancestor, no virtual elements, no middleware pipeline. If you need those, use Floating UI — it is the right tool and it is far better at positioning than this.

What we do not claim#

That Floating UI should not be used. The claim is the behaviour layer above it, which it does not attempt.

That the fallback is as good. A browser without the popover API gets a fixed-position panel, which is what every other library does all of the time — so it is no worse than the alternatives, just not as good as the main path.