Rendering Tooltips with React Portals (Without Breaking Layout)

While React Portals are commonly used for modals, they’re just as valuable for lightweight UI elements like tooltips and popovers. Tooltips often need to escape container boundaries (like overflow: hidden) and stack correctly above all other content. That’s exactly where React Portals shine.

In this article, we’ll use a portal to render a tooltip outside the parent component’s DOM tree — avoiding layout bugs and z-index conflicts.

Step 1: Set Up a Portal Root

Just like with modals, create a separate DOM node for your tooltip content in public/index.html:

This is where the tooltip will be mounted via a portal.

Step 2: Create the Tooltip Component

Let’s build a tooltip that renders via ReactDOM.createPortal and positions itself near a target element using getBoundingClientRect().

import React, { useEffect, useRef, useState } from "react";
import ReactDOM from "react-dom";

const tooltipRoot = document.getElementById("tooltip-root");

export default function Tooltip({ targetRef, text, visible }) {
  const [position, setPosition] = useState({ top: 0, left: 0 });
  const tooltipRef = useRef(null);

  useEffect(() => {
    if (visible && targetRef.current) {
      const rect = targetRef.current.getBoundingClientRect();
      setPosition({
        top: rect.bottom + window.scrollY + 8,
        left: rect.left + window.scrollX + rect.width / 2,
      });
    }
  }, [visible, targetRef]);

  if (!visible) return null;

  return ReactDOM.createPortal(
    

      {text}
    
,
    tooltipRoot
  );
}

Step 3: Style the Tooltip

Add basic styles for the floating tooltip:

.tooltip {
  position: absolute;
  transform: translateX(-50%);
  background: #222;
  color: #fff;
  padding: 6px 10px;
  border-radius: 4px;
  font-size: 0.875rem;
  white-space: nowrap;
  pointer-events: none;
  z-index: 1000;
}

This ensures the tooltip is small, centered above the target, and doesn't block pointer events.

Step 4: Use the Tooltip

Now let’s use it in a component:

import React, { useRef, useState } from "react";
import Tooltip from "./Tooltip";

function TooltipExample() {
  const btnRef = useRef();
  const [hovered, setHovered] = useState(false);

  return (
    

       setHovered(true)}
        onMouseLeave={() => setHovered(false)}
      >
        Hover me
      

      
    
  );
}

When the button is hovered, the tooltip appears — positioned outside the normal DOM flow, thanks to the portal.

✅ Why Use Portals for Tooltips:

• 🚫 Avoid clipping inside scrollable or overflow-hidden containers
• 🧼 Keeps z-index and stacking predictable
• 📦 Lightweight and easily reusable

Summary

React Portals aren’t just for full-screen modals — they’re perfect for tooltips, dropdowns, and overlays that need to “break out” of the DOM layout. By positioning your tooltip with getBoundingClientRect() and rendering it in a portal, you get precise control over placement and styling — without DOM headaches.

For a much more extensive guide on getting the most out of React portals, check out my full 24-page PDF file on Gumroad. It's available for just $10:

Using React Portals Like a Pro.

If this was helpful, you can also support me here: Buy Me a Coffee ☕