{"id":11827,"library":"react-popper-tooltip","title":"React Popper Tooltip","description":"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.","status":"active","version":"4.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/mohsinulhaq/react-popper-tooltip","tags":["javascript","react","tooltip","popover","overlay","react-tooltip","react-popper","typescript"],"install":[{"cmd":"npm install react-popper-tooltip","lang":"bash","label":"npm"},{"cmd":"yarn add react-popper-tooltip","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-popper-tooltip","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for React component and hook functionality.","package":"react","optional":false},{"reason":"Required for rendering React components to the DOM.","package":"react-dom","optional":false}],"imports":[{"note":"This is the primary named export for the hook API, introduced in v4.0.0. The render prop `TooltipTrigger` was removed in v4.","wrong":"import usePopperTooltip from 'react-popper-tooltip';","symbol":"usePopperTooltip","correct":"import { usePopperTooltip } from 'react-popper-tooltip';"},{"note":"Imports the optional default minimal CSS styles. Available since v3.1.0. This is a side-effect import and does not export any values.","symbol":"styles.css","correct":"import 'react-popper-tooltip/dist/styles.css';"},{"note":"Example of importing TypeScript types for stricter type checking and enhanced IDE support. The library ships with its own type definitions.","symbol":"UsePopperTooltipOptions","correct":"import type { UsePopperTooltipOptions } from 'react-popper-tooltip';"}],"quickstart":{"code":"import * as React from 'react';\nimport { render } from 'react-dom';\nimport { usePopperTooltip } from 'react-popper-tooltip';\nimport 'react-popper-tooltip/dist/styles.css';\n\nfunction App() {\n  const {\n    getArrowProps,\n    getTooltipProps,\n    setTooltipRef,\n    setTriggerRef,\n    visible,\n  } = usePopperTooltip();\n\n  return (\n    <div className=\"App\">\n      <button type=\"button\" ref={setTriggerRef}>\n        Trigger\n      </button>\n      {visible && (\n        <div\n          ref={setTooltipRef}\n          {...getTooltipProps({ className: 'tooltip-container' })}\n        >\n          <div {...getArrowProps({ className: 'tooltip-arrow' })} />\n          Tooltip Content\n        </div>\n      )}\n    </div>\n  );\n}\n\nrender(<App />, document.getElementById('root'));","lang":"typescript","description":"Demonstrates the basic usage of the `usePopperTooltip` hook with a simple button trigger and includes the default stylesheet for minimal styling and functionality."},"warnings":[{"fix":"Migrate any existing `TooltipTrigger` implementations to use the `usePopperTooltip` hook. Consult the official migration guide for detailed instructions and examples.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.1.0 <4.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Migrate your tooltip implementation to use the `usePopperTooltip` hook instead of `TooltipTrigger`.","cause":"Attempting to use the `TooltipTrigger` render prop component, which was removed in version 4.0.0.","error":"TypeError: (0 , react_popper_tooltip__WEBPACK_IMPORTED_MODULE_1__.TooltipTrigger) is not a function"},{"fix":"Ensure `usePopperTooltip` is imported as a named export: `import { usePopperTooltip } from 'react-popper-tooltip';`.","cause":"The `usePopperTooltip` hook was incorrectly imported as a default export instead of a named export.","error":"Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined."},{"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'`.","cause":"The default CSS styles (`dist/styles.css`) have not been imported, or custom styles are missing/incorrectly applied.","error":"Tooltip appears, but it is unstyled or looks like a plain div without an arrow."}],"ecosystem":"npm"}