react-popper

library2.3.0jsnpmunverified

react-popper is the official React wrapper library for Popper.js, a powerful positioning engine used to create tooltips, popovers, and other UI elements that need to be dynamically positioned relative to a reference element. It provides a declarative API for integrating Popper into React applications, abstracting away direct DOM manipulation. The current stable version is 2.3.0, which includes support for React 18. This library is actively maintained, with regular updates addressing bug fixes, TypeScript type improvements, and React version compatibility. Key differentiators include its tight integration with the highly optimized Popper.js core and a modern hook-based API (`usePopper`) introduced in v2.2.0, which simplifies complex positioning logic within functional components, offering a more idiomatic React experience compared to earlier render-prop patterns.

web-framework

npm install react-popper

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-POPPER

react-popper

web-frameworkjavascriptv2.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

usePopper

✓ import { usePopper } from 'react-popper'

✗ const { usePopper } = require('react-popper')

Introduced in v2.2.0 as the primary hook-based API for functional components. Prefer this over render-props.

Popper

✓ import { Popper } from 'react-popper'

✗ const { Popper } = require('react-popper')

The render-prop component for positioning. Still available but `usePopper` is generally preferred for new code.

Manager

✓ import { Manager } from 'react-popper'

✗ const { Manager } = require('react-popper')

The context provider that manages the reference and popper elements. Required when using `Popper` and `Reference` components.

Reference

✓ import { Reference } from 'react-popper'

The render-prop component to define the reference element for `Popper`. Used in conjunction with `Manager`.

Demonstrates a basic tooltip implementation using the `usePopper` hook, including placement, offset, and an arrow modifier.

import React, { useState } from 'react'; import { usePopper } from 'react-popper'; function TooltipButton() { const [referenceElement, setReferenceElement] = useState(null); const [popperElement, setPopperElement] = useState(null); const [arrowElement, setArrowElement] = useState(null); const [isVisible, setIsVisible] = useState(false); const { styles, attributes } = usePopper(referenceElement, popperElement, { placement: 'right', modifiers: [ { name: 'arrow', element: arrowElement }, { name: 'offset', options: { offset: [0, 8] } }, ], }); return ( <> <button type="button" ref={setReferenceElement} onMouseEnter={() => setIsVisible(true)} onMouseLeave={() => setIsVisible(false)} style={{ padding: '10px 20px', fontSize: '16px', cursor: 'pointer' }} > Hover Me </button> {isVisible && ( <div ref={setPopperElement} style={{ ...styles.popper, background: 'rgba(0,0,0,0.8)', color: 'white', padding: '5px 10px', borderRadius: '4px', zIndex: 1000 }} {...attributes.popper} > This is a tooltip! <div ref={setArrowElement} style={styles.arrow} /> </div> )} </> ); } // To render in a React app: // ReactDOM.render(<TooltipButton />, document.getElementById('root'));

Debug

Known issues

breakingVersion 2.0.0 migrated to `@popperjs/core` v2, which introduced significant internal changes to Popper.js. While `react-popper` aimed for backward compatibility where possible, direct usage of Popper.js options or custom modifiers might need adjustments.

fix

Ensure `@popperjs/core` is installed at version `^2.0.0`. Review any custom Popper options or modifiers for compatibility with Popper v2 API changes, referring to the `@popperjs/core` documentation.

affects: >=2.0.0

gotchaUsing CommonJS `require()` syntax with `react-popper` versions prior to 2.2.1 could lead to bundle issues or unexpected behavior due to improper CommonJS module exports.

fix

Upgrade to `react-popper` v2.2.1 or newer. Always prefer ESM `import` statements for better tooling compatibility and tree-shaking.

affects: <2.2.1

gotchaIncorrect or outdated TypeScript types, particularly for `usePopper`'s `update` and `forceUpdate` methods, as well as general compatibility with latest `@popperjs/core` types, have been reported in various minor versions.

fix

Update to `react-popper` v2.2.4 or later to get the most recent TypeScript type fixes and improved Flow types, ensuring better compatibility with `@popperjs/core`.

affects: 2.2.0 - 2.2.3

gotcha`@popperjs/core` is a mandatory peer and runtime dependency. Failing to install it alongside `react-popper` will result in runtime errors.

fix

Always install both packages: `npm i react-popper @popperjs/core` or `yarn add react-popper @popperjs/core`.

affects: >=1.0.0

gotchaThe `usePopper` hook, introduced in v2.2.0, is a complete rewrite and the recommended API. While render-prop components like `Popper`, `Manager`, `Reference` are still supported, they are generally less ergonomic for functional components.

fix

For new implementations or refactoring, prioritize using the `usePopper` hook. Refer to the official documentation for examples.

affects: >=2.2.0

Errors

Common errors & fixes

Error: Element passed to the reference argument (or `referenceElement`) is null.

The reference element for Popper has not been properly provided or mounted before Popper attempts to initialize.

fix

Ensure the `referenceElement` prop (or the ref setter function in `usePopper`) is correctly assigned to a DOM element that is rendered, or that the element is available when the Popper instance is created. Use `useState` and `useCallback` for refs with `usePopper`.

Error: Popper: `arrow` modifier is not set up correctly. You have to pass the DOM node of the arrow element to the `arrow.element` modifier option.

When using the `arrow` modifier, the actual arrow DOM element must be explicitly passed to the modifier's options.

fix

In the `modifiers` array, for the `arrow` modifier, add `element: arrowElement` where `arrowElement` is a ref to your arrow DOM node (e.g., `<div ref={setArrowElement} />`).

TypeError: Cannot read properties of undefined (reading 'placement')

Often occurs when `styles` or `attributes` from `usePopper` are accessed before the popper instance is fully initialized, or if `usePopper` is not correctly called with reference and popper elements.

fix

Ensure `referenceElement` and `popperElement` states are properly managed and passed to `usePopper`. Also, ensure that the Popper component (or the JSX where styles are applied) is only rendered when `isVisible` (or a similar state) is true, to prevent accessing undefined `styles` or `attributes`.

Upgrade

Version history

2.3.0latest on npm

Audit

Dependencies

@popperjs/corerequiredRequired runtime dependency for the underlying positioning engine.

reactrequiredPeer dependency for React applications.

react-domrequiredPeer dependency for rendering React components.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/popperjs/react-popper ↗

packagehttps://www.npmjs.com/package/react-popper ↗

homepagehttps://popper.js.org/react-popper ↗