Popper

Popper is a small, dependency-free JavaScript positioning engine for “floating” UI elements such as tooltips, popovers, dropdowns, and context menus. Given a reference element and a floating element, it computes the optimal position, keeps the pair aligned through scrolling and resizing, and automatically flips or shifts the element to avoid clipping at the edges of the viewport or any scrolling container.

Built around a tree-shakeable modifier pipeline, Popper handles the countless edge cases of cross-browser positioning (RTL, scrollbars, nested offset parents, virtual elements) so you don’t have to. It powers the overlay primitives of libraries like Bootstrap, Material UI, and Foundation, and integrates cleanly with React, Vue, and Angular.

What You Get

• A createPopper(reference, popper, options) constructor that positions a floating element relative to a reference element.
• A library of built-in modifiers for offset, flipping, overflow prevention, arrow placement, and event-driven updates.
• Collision detection that automatically flips and shifts the element to stay visible within the viewport or scrolling containers.
• Tree-shakeable ESM builds plus UMD/CDN bundles, along with a smaller createPopperLite entry point for size-sensitive apps.
• Support for virtual elements, letting you position relative to arbitrary coordinates such as the mouse cursor.

Common Use Cases

• Positioning tooltips that stay attached to a button while the page scrolls.
• Building dropdown menus and select popups that flip above the trigger when there is no room below.
• Rendering popovers and context menus that follow the cursor via a virtual reference element.
• Powering overlay primitives inside design systems and component libraries.

Under The Hood

Architecture

Popper is organized around a modifier lifecycle orchestrated by popperGenerator in src/createPopper.js. Calling createPopper builds an Instance holding a state object (rects, styles, placement, options); on each update() the engine reads layout via dom-utils helpers (getCompositeRect, getLayoutRect, listScrollParents, getOffsetParent), then runs an ordered list of modifiers through their read and write phases. Modifiers in src/modifiers/ — offset, flip, preventOverflow, arrow, computeStyles, applyStyles, eventListeners, popperOffsets, hide — each mutate state.modifiersData, and orderModifiers topologically sorts them by their requires/requiresIfExists declarations. index.js re-exports the full createPopper, a createPopperLite, and the low-level popperGenerator/detectOverflow primitives.

Tech Stack

The source is authored in JavaScript with Flow type annotations and ships hand-maintained TypeScript definitions (index.d.ts). It has zero runtime dependencies. The build toolchain compiles ES modules with Babel, produces UMD/CJS/ESM bundles with Rollup, generates TypeScript types via flow-to-ts, and lints with ESLint and Prettier. It is marked sideEffects: false to enable aggressive tree-shaking.

Code Quality

The codebase is small, focused, and well-tested. Unit tests (Jest) sit next to the code they cover (roughly 19 *.test.js files across modifiers, utils, and the core constructor) with snapshot coverage, alongside separate tests/functional (browser), tests/visual, tests/flowtype, and tests/typescript suites that validate real positioning behavior across environments. Naming is consistent and the pure-function modifier design keeps logic easy to reason about and test in isolation.

API Design

The public surface is intentionally minimal: one createPopper call plus a declarative modifiers array. Sensible defaults (bottom placement, absolute strategy) mean a working popper needs almost no configuration, while the modifier system exposes deep customization and even custom modifiers for advanced cases. The Lite entry point and CDN bundles lower the barrier to getting started, and the TypeScript/Flow types make options discoverable in editors.