Tiny (~1.8KB), zero-dependency positioning engine for tooltips, popovers, and dropdowns. Supports React, Vue, Svelte, Solid, and Angular
npm install pop-perfect




> Stop fighting the DOM. Start shipping UI.
> The zero-dependency geometry engine that positions your tooltips, popups, and dropdowns perfectly. Every. Single. Time.
You use getBoundingClientRect() to position elements. You are breaking your mobile UI.
Native positioning fails in these common scenarios:
- ❌ Mobile Keyboards: The virtual keyboard pushes the viewport, covering your popup.
- ❌ Clipping: Parent containers with overflow: hidden cut off your tooltips.
- ❌ Edge Collisions: Menus open off-screen on smaller devices.
- ❌ Scroll Chaos: Nested scrollable containers break coordinate calculations.
PopPerfect solves this. It combines ResizeObserver, Visual Viewport API, and GPU-accelerated transforms to guarantee perfect placement.
- Universal: First-class support for React, Vue, Svelte, Solid, Angular, and Vanilla.
- Tiny: ~1.8KB gzipped.
- Smart: Uses requestAnimationFrame to prevent main-thread blocking.
---
``bash`
npm install pop-perfector
pnpm add pop-perfector
yarn add pop-perfect
---
Use the usePopPosition hook.
`jsx
import { usePopPosition } from 'pop-perfect/react'
const Tooltip = ({ triggerRef }) => {
// Returns a ref to attach and styles to apply
const { ref, style } = usePopPosition(triggerRef, {
placement: 'top',
offset: 10
})
return
$3
Use the
usePopPosition composable.`html
Vue Magic ✨
`$3
Use the
popPerfect action.`svelte
Svelte Action!
`$3
Use the
popPerfect directive.`tsx
iimport { createSignal } from 'solid-js';
import { popPerfect } from 'pop-perfect/solid';// Typescript: declare module 'solid-js' { namespace JSX { interface Directives { popPerfect: any; } } }
function App() {
const [trigger, setTrigger] = createSignal();
const [show, setShow] = createSignal(false);
return (
<>
Solid Reactivity ⚡️
>
);
}
`$3
Use the standalone
PopPerfectDirective.`typescript
import { Component } from '@angular/core';
import { PopPerfectDirective } from 'pop-perfect/angular';@Component({
selector: 'app-dropdown',
standalone: true,
imports: [PopPerfectDirective],
template:
})
export class DropdownComponent {
isOpen = true;
}`$3
`js
import { PopEngine } from 'pop-perfect'const trigger = document.querySelector('#btn')
const popup = document.querySelector('#tooltip')
const engine = new PopEngine(trigger, popup, {
placement: 'top',
flip: true
})
// Later
// engine.destroy()
`---
Configuration ⚙️
You can customize the behavior of the positioning engine.
`js
// React example
usePopPosition(triggerRef, {
placement: 'bottom-end',
offset: 12,
flip: true,
strategy: 'fixed'
})
`
| Feature | PopPerfect 💎 | Native getBoundingClientRect | Heavy Libs (Popper/Floating) |
| :--- | :---: | :---: | :---: |
| Size (Gzipped) | ~1.8kb | 0kb | ~6kb - 20kb |
| Edge Cases | Handled (100+) | You handle them manually 💀 | Handled |
| Setup Time | 30 seconds | Hours of debugging | Moderate |
| Performance | RAF Optimized | Manual optimization needed | Good |
| DX | Hook/Directive | Imperative spaghetti | Configuration heavy |---
How it works 🧊
PopPerfect uses a "Reactive Geometry" architecture to keep performance high:
1. The Watcher: It uses
ResizeObserver on both the trigger and the popup. If content changes size, the position updates instantly.
2. Mobile Guard: It listens to the VisualViewport API. When an iOS keyboard slides up, PopPerfect adjusts coordinates so your UI isn't buried.
3. The Math: It calculates collisions with window edges. If flip: true is set, it detects if 'top' will be clipped and seamlessly switches to 'bottom'.
4. GPU Rendering: Coordinates are applied using transform: translate3d(...). This promotes the element to its own composite layer, ensuring 60 FPS animations without layout thrashing.
Support the project ❤️
> "We eliminated the manual getBoundingClientRect math, saved your mobile users from keyboards covering their inputs, and absorbed the VisualViewport API nightmare. You saved dozens of hours not reinventing a positioning engine that would have broken inside nested scroll containers anyway. Your donation is a fair trade for pixel-perfect UI and weekends free from math debugging."If this library saved you time, please consider supporting the development:
1. Fiat (Cards/PayPal): via Boosty (one-time or monthly).
2. Crypto (USDT/TON/BTC/ETH): view wallet addresses on Telegram.
License
MIT
Keywords
tooltip popover dropdown menu positioning floating anchor overlay react vue svelte solid angular typescript headless ui`