React Tooltip Component

Common errors

• Cannot import the named export 'Tooltip' from 'react-tooltip' (only default export is available)

  cause Attempting to use named import syntax for `Tooltip` in a v4 codebase or in a v5 setup where a bundler incorrectly treats the module as CommonJS.
  fix For v5+, ensure you are using `import { Tooltip } from 'react-tooltip';`. If the error persists, check your bundler configuration for proper ESM handling (e.g., Webpack's `javascript/auto` for `.mjs` files). For v4, use `import ReactTooltip from 'react-tooltip';`.

• Tooltip is not showing up or not appearing on hover/click.

  cause The `id` on the `Tooltip` component does not match the `data-tooltip-id` attribute on the anchor element, or the required styles are not loaded.
  fix Verify that the `id` prop on `<Tooltip>` exactly matches the `data-tooltip-id` attribute on your interactive element. Also, ensure that `react-tooltip`'s default styles are being imported (e.g., `import 'react-tooltip/dist/react-tooltip.css';`).

• Tooltip content is not updating dynamically after state changes.

  cause In v4, users expected to call `ReactTooltip.rebuild()`. In v5, while automatic, complex DOM manipulations or certain rendering patterns might cause issues if the component doesn't detect changes.
  fix Ensure you are on v5+ (which handles updates automatically). If on v4, call `ReactTooltip.rebuild()` after dynamic content changes. For v5, if automatic updates fail, ensure your anchor element is correctly rendered and its `data-tooltip-content` or `content` prop is bound to reactive state. Consider using the `setIsOpen` prop for explicit control in complex scenarios.

• Type 'Element' is not assignable to type 'ReactElement<any, any> | null' in TypeScript with `TooltipRef`.

  cause Incorrectly assigning a non-ReactElement type to a ref that expects a React element or component instance for `TooltipRef`.
  fix Ensure that the `ref` prop is correctly attached to the `Tooltip` component instance, e.g., `const tooltipRef = useRef<TooltipRef>(null); <Tooltip ref={tooltipRef} ... />`. Avoid manually trying to set the ref to a DOM element directly when the type expects a component ref.

Warnings

• breaking Major breaking changes occurred in v5. All data attributes are now prefixed with `data-tooltip-`. For example, `data-for` became `data-tooltip-id` and `data-tip` became `data-tooltip-content`.
  Fix: Update anchor elements to use the new `data-tooltip-` prefixed attributes (e.g., `data-tooltip-id` and `data-tooltip-content`). Refer to the v4->v5 changelog for a complete list.
• breaking The main component export changed from a default export named `ReactTooltip` in v4 to a named export `Tooltip` in v5.
  Fix: Change your import statements from `import ReactTooltip from 'react-tooltip';` to `import { Tooltip } from 'react-tooltip';`.
• breaking The `ReactTooltip.rebuild()` method, used in v4 for dynamic content updates, was removed in v5. Tooltips now automatically watch for DOM changes.
  Fix: Remove all calls to `ReactTooltip.rebuild()`. The component now handles updates automatically. If issues arise, report them with a reproducible example.
• breaking The `getContent` prop was removed in v5, and content is primarily managed via `data-tooltip-content` or the `content` prop on the `Tooltip` component.
  Fix: Refactor content provision to use `data-tooltip-content` attribute on the anchor or the `content` prop directly on the `Tooltip` component.
• gotcha The default behavior of the tooltip's effect changed from `float` to `solid` in v5.
  Fix: If you require the `float` effect, explicitly set the `effect` prop to `float` on your `Tooltip` component: `<Tooltip effect="float" ... />`.
• gotcha Bundling issues can occur in some environments (e.g., SPFx) where `react-tooltip`'s ESM module is incorrectly treated as CommonJS, leading to 'Can't import named export from non EcmaScript module' errors.
  Fix: Ensure your bundler (e.g., Webpack) is correctly configured to handle `.mjs` files and ESM modules within `node_modules`. This may involve adding rules like `{ test: /\.mjs$/, include: /node_modules/, type: 'javascript/auto' }` to your Webpack configuration.

Install

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

Imports

• Tooltip
  wrong:

  import ReactTooltip from 'react-tooltip';

  correct:

  import { Tooltip } from 'react-tooltip';

  Since v5, the main component is a named export `Tooltip`, not a default export `ReactTooltip` like in v4. Always use named import.
• ITooltipController

  import type { ITooltipController } from 'react-tooltip';

  Type import for programmatic control methods available via refs, useful for TypeScript projects.
• TooltipRef

  import type { TooltipRef } from 'react-tooltip';

  Type import for the ref object used to access programmatic methods of the Tooltip component.

Quickstart

Demonstrates basic hover and click triggered tooltips, along with programmatic control.

import React, { useRef, useState } from 'react';
import { Tooltip, TooltipRef } from 'react-tooltip';

function MyComponent() {
  const tooltipRef = useRef<TooltipRef>(null);
  const [isTooltipOpen, setIsTooltipOpen] = useState(false);

  const showProgrammaticTooltip = () => {
    if (tooltipRef.current) {
      tooltipRef.current.showTooltip();
      setIsTooltipOpen(true);
    }
  };

  const hideProgrammaticTooltip = () => {
    if (tooltipRef.current) {
      tooltipRef.current.hideTooltip();
      setIsTooltipOpen(false);
    }
  };

  return (
    <div>
      <a
        data-tooltip-id="my-hover-tooltip"
        data-tooltip-content="Hello, hover world!"
      >
        Hover over me
      </a>
      <Tooltip id="my-hover-tooltip" />

      <br /><br />

      <button
        data-tooltip-id="my-click-tooltip"
        data-tooltip-content="Click me for content!"
      >
        Click for Tooltip
      </button>
      <Tooltip id="my-click-tooltip" place="right" events={['click']} />

      <br /><br />

      <button onClick={showProgrammaticTooltip} disabled={isTooltipOpen}>
        Show Programmatic Tooltip
      </button>
      <button onClick={hideProgrammaticTooltip} disabled={!isTooltipOpen}>
        Hide Programmatic Tooltip
      </button>
      <span
        id="programmatic-anchor"
        style={{ marginLeft: '10px', padding: '5px', border: '1px solid gray' }}
      >
        Anchor
      </span>
      <Tooltip
        id="programmatic-tooltip"
        content="I'm controlled by buttons!"
        isOpen={isTooltipOpen}
        setIsOpen={setIsTooltipOpen}
        anchorSelect="#programmatic-anchor"
        ref={tooltipRef}
        place="bottom"
      />
    </div>
  );
}

export default MyComponent;