React Popper Tooltip

4.4.2 · active · verified Sun Apr 19

react-popper-tooltip is a React library that provides a flexible hook (`usePopperTooltip`) for creating smart, accessible tooltips, popovers, and overlays. It leverages the robust positioning engine of `react-popper` (which in turn uses `popper.js`) under the hood. Currently at version 4.4.2, the library shows an active release cadence with frequent patch and minor updates addressing bugs and adding features like Shadow DOM support and improved hover mechanics. A key differentiator since its v4 release is the exclusive reliance on a hook-based API, moving away from older render prop patterns for a more modern and flexible developer experience. It provides optional default styling but is designed to be highly customizable with any CSS or CSS-in-JS solution.

Common errors

```
TypeError: (0 , react_popper_tooltip__WEBPACK_IMPORTED_MODULE_1__.TooltipTrigger) is not a function
```
cause Attempting to use the `TooltipTrigger` render prop component, which was removed in version 4.0.0.

fix Migrate your tooltip implementation to use the `usePopperTooltip` hook instead of `TooltipTrigger`.
```
Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined.
```
cause The `usePopperTooltip` hook was incorrectly imported as a default export instead of a named export.

fix Ensure `usePopperTooltip` is imported as a named export: `import { usePopperTooltip } from 'react-popper-tooltip';`.
```
Tooltip appears, but it is unstyled or looks like a plain div without an arrow.
```
cause The default CSS styles (`dist/styles.css`) have not been imported, or custom styles are missing/incorrectly applied.

fix Add `import 'react-popper-tooltip/dist/styles.css';` to your project's entry point, or apply custom CSS to elements with `className='tooltip-container'` and `className='tooltip-arrow'`.

Warnings

breaking Version 4.0.0 introduced a significant breaking change by deprecating and removing the `TooltipTrigger` render prop API. The `usePopperTooltip` hook is now the exclusive and recommended way to create tooltips.
Fix: Migrate any existing `TooltipTrigger` implementations to use the `usePopperTooltip` hook. Consult the official migration guide for detailed instructions and examples.
gotcha Versions 4.1.0 and 4.1.2 introduced and attempted to fix issues with a new hover trigger mechanism, which had unintended side effects impacting tooltip interactions. Version 4.2.0 reverted to an older, more stable hover mechanic while addressing previous problems.
Fix: Ensure you are using `react-popper-tooltip` version `4.2.0` or higher to benefit from the stable hover trigger implementation and avoid known bugs from the `4.1.x` releases.
gotcha The primary documentation on the GitHub repository and npmjs.com is for v4.x and the `usePopperTooltip` hook API. If you are using the older v3.x render prop API, you must refer to the v3-specific documentation as the current docs will not be applicable.
Fix: For users on v3.x, consult the archived documentation at `https://github.com/mohsinulhaq/react-popper-tooltip/blob/v3/README.md`. For new projects or upgrades, use v4.x and the `usePopperTooltip` hook.
gotcha While `react-popper-tooltip` provides a `dist/styles.css` file for basic styling, it is not automatically applied. Developers must manually import this file or provide their own custom styling for the tooltip container and arrow elements to achieve a visual tooltip.
Fix: Add `import 'react-popper-tooltip/dist/styles.css';` to your application's entry file, or define custom CSS rules targeting the `tooltip-container` and `tooltip-arrow` classes, leveraging `data-popper-placement` attributes for positional styling.

Install

npm install react-popper-tooltip npm
yarn add react-popper-tooltip yarn
pnpm add react-popper-tooltip pnpm

Imports

usePopperTooltip
wrong:
```
import usePopperTooltip from 'react-popper-tooltip';
```
correct:
```
import { usePopperTooltip } from 'react-popper-tooltip';
```
This is the primary named export for the hook API, introduced in v4.0.0. The render prop `TooltipTrigger` was removed in v4.
styles.css
```
import 'react-popper-tooltip/dist/styles.css';
```
Imports the optional default minimal CSS styles. Available since v3.1.0. This is a side-effect import and does not export any values.
UsePopperTooltipOptions
```
import type { UsePopperTooltipOptions } from 'react-popper-tooltip';
```
Example of importing TypeScript types for stricter type checking and enhanced IDE support. The library ships with its own type definitions.

Quickstart

Demonstrates the basic usage of the `usePopperTooltip` hook with a simple button trigger and includes the default stylesheet for minimal styling and functionality.

import * as React from 'react';
import { render } from 'react-dom';
import { usePopperTooltip } from 'react-popper-tooltip';
import 'react-popper-tooltip/dist/styles.css';

function App() {
  const {
    getArrowProps,
    getTooltipProps,
    setTooltipRef,
    setTriggerRef,
    visible,
  } = usePopperTooltip();

  return (
    <div className="App">
      <button type="button" ref={setTriggerRef}>
        Trigger
      </button>
      {visible && (
        <div
          ref={setTooltipRef}
          {...getTooltipProps({ className: 'tooltip-container' })}
        >
          <div {...getArrowProps({ className: 'tooltip-arrow' })} />
          Tooltip Content
        </div>
      )}
    </div>
  );
}

render(<App />, document.getElementById('root'));

view raw JSON →