feat(tooltip): Enable custom portal container for tooltip

packages/visx-demo/src/sandboxes/visx-tooltip/Example.tsx

@@ -1,4 +1,5 @@
 import React, { useState, useCallback } from 'react';
+import ReactDOM from 'react-dom';
 import {
   Tooltip,
   TooltipWithBounds,
@@ -26,13 +27,41 @@ const tooltipStyles = {
   padding: 12,
 };
 
+type OverlayLayerProps = {
+  container: HTMLDivElement | null;
+  text: string;
+  className?: string;
+  placeAfterTooltipInDom?: boolean;
+};
+
+function OverlayLayer({ className, container, placeAfterTooltipInDom, text }: OverlayLayerProps) {
+  if (container) {
+    // Since we re-render the tooltip every time the pointer moves and its DOM node
+    // is placed at the end of the container, if placeAfterTooltipInDom is true we
+    // also want to re-render the overlay layer
+    const key = placeAfterTooltipInDom ? Math.random() : 'overlay-under';
+    return ReactDOM.createPortal(
+      <div className={className} key={key}>
+        {text}
+      </div>,
+      container,
+    );
+  }
+  return null;
+}
+
 export default function Example({ width, height, showControls = true }: TooltipProps) {
   const [tooltipShouldDetectBounds, setTooltipShouldDetectBounds] = useState(true);
+  const [tooltipShouldUseCustomContainer, setTooltipShouldUseCustomContainer] = useState(true);
   const [renderTooltipInPortal, setRenderTooltipInPortal] = useState(false);
+  const overlayRootRef = React.useRef<HTMLDivElement | null>(null);
 
   const { containerRef, containerBounds, TooltipInPortal } = useTooltipInPortal({
     scroll: true,
     detectBounds: tooltipShouldDetectBounds,
+    portalContainer: tooltipShouldUseCustomContainer
+      ? overlayRootRef.current ?? undefined
+      : undefined,
   });
 
   const {
@@ -81,6 +110,12 @@ export default function Example({ width, height, showControls = true }: TooltipP
         style={{ width, height }}
         onPointerMove={handlePointerMove}
       >
+        <div className="overlay-root" ref={overlayRootRef} />
+        <OverlayLayer
+          className="overlay-layer overlay-under-tooltip"
+          container={overlayRootRef.current}
+          text="We want this to appear under the tooltip."
+        />
         {tooltipOpen ? (
           <>
             <div
@@ -115,6 +150,12 @@ export default function Example({ width, height, showControls = true }: TooltipP
         ) : (
           <div className="no-tooltip">Move or touch the canvas to see the tooltip</div>
         )}
+        <OverlayLayer
+          className="overlay-layer overlay-over-tooltip"
+          container={overlayRootRef.current}
+          placeAfterTooltipInDom // Force DOM node to be placed after tooltip for demo purposes
+          text="We want this to appear over the tooltip."
+        />
         <div className="z-index-bummer">
           I have an annoying z-index. Try&nbsp;
           <label>
@@ -146,6 +187,19 @@ export default function Example({ width, height, showControls = true }: TooltipP
             &nbsp;Tooltip with boundary detection
           </label>
 
+          {renderTooltipInPortal && (
+            <label>
+              <input
+                type="checkbox"
+                checked={tooltipShouldUseCustomContainer}
+                onChange={() =>
+                  setTooltipShouldUseCustomContainer(!tooltipShouldUseCustomContainer)
+                }
+              />
+              &nbsp;Tooltip portal in custom container
+            </label>
+          )}
+
           <button onClick={() => hideTooltip()}>Hide tooltip</button>
         </div>
       )}
@@ -205,6 +259,25 @@ export default function Example({ width, height, showControls = true }: TooltipP
           padding: 16px;
           line-height: 1.2em;
         }
+        .overlay-root {
+          z-index: 3000;
+          position: relative;
+        }
+        .overlay-layer {
+          position: absolute;
+          border-radius: 8px;
+          padding: 8px;
+        }
+        .overlay-under-tooltip {
+          top: 30px;
+          right: 10px;
+          background: rgba(52, 235, 180, 0.8);
+        }
+        .overlay-over-tooltip {
+          top: 70px;
+          right: 30px;
+          background: rgba(250, 235, 180, 0.8);
+        }
       `}</style>
     </>
   );

packages/visx-tooltip/Readme.md

@@ -113,7 +113,8 @@ object or inject it cleanly using the `polyfill` config option below.
 
 `useTooltipInPortal` is a hook which gives you a `TooltipInPortal` component for rendering `Tooltip`
 or `TooltipWithBounds` in a `Portal`, outside of your component DOM tree which can be useful in many
-circumstances (see below for more on `Portal`s).
+circumstances (see below for more on `Portal`s). A custom portal container can be provided
+via the `portalContainer` config option.
 
 ##### API
 
@@ -128,7 +129,9 @@ type Options = {
   scroll?: boolean
   /** You can optionally inject a resize-observer polyfill */
   polyfill?: { new (cb: ResizeObserverCallback): ResizeObserver }
-  /** Optional z-index to set on the Portal div */
+  /** Optional container for the portal. */
+  portalContainer?: HTMLDivElement;
+  /** Optional z-index to set on the Portal div (not applicable when a specific portal container is provided) */
   zIndex?: number | string;
 }
 

packages/visx-tooltip/package.json

@@ -28,6 +28,7 @@
   },
   "homepage": "https://github.com/airbnb/visx#readme",
   "dependencies": {
+    "@react-hook/resize-observer": "^1.2.6",
     "@types/react": "*",
     "@visx/bounds": "3.0.0",
     "classnames": "^2.3.1",

packages/visx-tooltip/src/Portal.tsx

@@ -2,7 +2,9 @@ import React from 'react';
 import ReactDOM from 'react-dom';
 
 export type PortalProps = {
-  /** Optional z-index to set on the Portal. */
+  /** Optional container for the Portal. */
+  container?: HTMLDivElement;
+  /** Optional z-index to set on the Portal (not applicable when a specific portal container is provided). */
   zIndex?: number | string;
   /** Content to render in the Portal. */
   children: NonNullable<React.ReactNode>;
@@ -13,13 +15,17 @@ export default class Portal extends React.PureComponent<PortalProps> {
   private node?: HTMLDivElement;
 
   componentWillUnmount() {
-    if (this.node && document.body) {
+    if (this.node && document.body && !this.props.container) {
       document.body.removeChild(this.node);
       delete this.node;
     }
   }
 
   render() {
+    if (!this.node && this.props.container) {
+      this.node = this.props.container;
+    }
+
     // SSR check
     if (!this.node && typeof document !== 'undefined') {
       this.node = document.createElement('div');

packages/visx-tooltip/src/hooks/useTooltipInPortal.tsx

@@ -1,12 +1,13 @@
-import React, { useMemo } from 'react';
+import React, { useCallback, useMemo, useState } from 'react';
 import useMeasure, { RectReadOnly, Options as BaseUseMeasureOptions } from 'react-use-measure';
+import useResizeObserver from '@react-hook/resize-observer';
 
 import Portal, { PortalProps } from '../Portal';
 import Tooltip, { TooltipProps } from '../tooltips/Tooltip';
 import TooltipWithBounds from '../tooltips/TooltipWithBounds';
 
 export type TooltipInPortalProps = TooltipProps &
-  Pick<UseTooltipPortalOptions, 'detectBounds' | 'zIndex'>;
+  Pick<UseTooltipPortalOptions, 'detectBounds' | 'portalContainer' | 'zIndex'>;
 
 export type UseTooltipInPortal = {
   containerRef: (element: HTMLElement | SVGElement | null) => void;
@@ -24,6 +25,8 @@ export type UseTooltipPortalOptions = Pick<PortalProps, 'zIndex'> & {
   scroll?: boolean;
   /** You can optionally inject a ResizeObserver polyfill. */
   polyfill?: BaseUseMeasureOptions['polyfill'];
+  /** Optional container for the portal. */
+  portalContainer?: HTMLDivElement;
 };
 
 /**
@@ -32,16 +35,34 @@ export type UseTooltipPortalOptions = Pick<PortalProps, 'zIndex'> & {
  */
 export default function useTooltipInPortal({
   detectBounds: detectBoundsOption = true,
+  portalContainer,
   zIndex: zIndexOption,
   ...useMeasureOptions
 }: UseTooltipPortalOptions | undefined = {}): UseTooltipInPortal {
   const [containerRef, containerBounds, forceRefreshBounds] = useMeasure(useMeasureOptions);
 
+  const [portalContainerRect, setPortalContainerRect] = useState<DOMRect | null>(
+    portalContainer?.getBoundingClientRect() ?? null,
+  );
+
+  const updatePortalContainerRect = useCallback(() => {
+    if (portalContainer) {
+      setPortalContainerRect(portalContainer?.getBoundingClientRect());
+    }
+  }, [portalContainer]);
+
+  React.useEffect(updatePortalContainerRect, [
+    containerBounds,
+    portalContainer,
+    updatePortalContainerRect,
+  ]);
+  useResizeObserver(portalContainer ?? null, updatePortalContainerRect);
+
   const TooltipInPortal = useMemo(
     () =>
       function ({
-        left: containerLeft = 0,
-        top: containerTop = 0,
+        left: tooltipLeft = 0,
+        top: tooltipTop = 0,
         detectBounds: detectBoundsProp, // allow override at component-level
         zIndex: zIndexProp, // allow override at the component-level
         ...tooltipProps
@@ -50,16 +71,41 @@ export default function useTooltipInPortal({
         const zIndex = zIndexProp == null ? zIndexOption : zIndexProp;
         const TooltipComponent = detectBounds ? TooltipWithBounds : Tooltip;
         // convert container coordinates to page coordinates
-        const portalLeft = containerLeft + (containerBounds.left || 0) + window.scrollX;
-        const portalTop = containerTop + (containerBounds.top || 0) + window.scrollY;
+        const portalLeft = portalContainer
+          ? tooltipLeft - (portalContainerRect?.left || 0) + (containerBounds.left || 0)
+          : tooltipLeft + (containerBounds.left || 0) + window.scrollX;
+        const portalTop = portalContainer
+          ? tooltipTop - (portalContainerRect?.top || 0) + (containerBounds.top || 0)
+          : tooltipTop + (containerBounds.top || 0) + window.scrollY;
+
+        const additionalTooltipProps =
+          detectBounds && portalContainer
+            ? {
+                portalContainerPosition: {
+                  left: portalContainerRect?.left || 0,
+                  top: portalContainerRect?.top || 0,
+                },
+                visualParentRect: {
+                  width: containerBounds.width,
+                  height: containerBounds.height,
+                  left: containerBounds.left,
+                  top: containerBounds.top,
+                },
+              }
+            : {};
 
         return (
-          <Portal zIndex={zIndex}>
-            <TooltipComponent left={portalLeft} top={portalTop} {...tooltipProps} />
+          <Portal container={portalContainer} zIndex={zIndex}>
+            <TooltipComponent
+              left={portalLeft}
+              top={portalTop}
+              {...tooltipProps}
+              {...additionalTooltipProps}
+            />
           </Portal>
         );
       },
-    [detectBoundsOption, zIndexOption, containerBounds.left, containerBounds.top],
+    [containerBounds, detectBoundsOption, portalContainer, portalContainerRect, zIndexOption],
   );
 
   return {

packages/visx-tooltip/src/tooltips/TooltipWithBounds.tsx

@@ -6,7 +6,20 @@ import { TooltipPositionProvider } from '../context/TooltipPositionContext';
 
 export type TooltipWithBoundsProps = TooltipProps &
   React.HTMLAttributes<HTMLDivElement> &
-  WithBoundingRectsProps & { nodeRef?: React.Ref<HTMLDivElement> };
+  WithBoundingRectsProps & {
+    nodeRef?: React.Ref<HTMLDivElement>;
+    /**
+     * When the tooltip is in a portal, this is the position of the portal
+     * container to be used for offsetting calculations around bounds as a consequence.
+     */
+    portalContainerPosition?: { left: number; top: number };
+    /**
+     * When the tooltip is in a portal, the portal container becomes the direct parent of the tooltip.
+     * Often the portal is not what we want the tooltip to be bound to. Another visual parent can be specified
+     * by specifying its dimensions here.
+     */
+    visualParentRect?: { width: number; height: number; left: number; top: number };
+  };
 
 function TooltipWithBounds({
   children,
@@ -20,19 +33,26 @@ function TooltipWithBounds({
   top: initialTop = 0,
   unstyled = false,
   nodeRef,
+  portalContainerPosition,
+  visualParentRect: visualParentBounds = parentBounds,
   ...otherProps
 }: TooltipWithBoundsProps) {
   let transform: React.CSSProperties['transform'];
   let placeTooltipLeft = false;
   let placeTooltipUp = false;
 
-  if (ownBounds && parentBounds) {
+  if (ownBounds && visualParentBounds) {
     let left = initialLeft;
     let top = initialTop;
 
-    if (parentBounds.width) {
-      const rightPlacementClippedPx = left + offsetLeft + ownBounds.width - parentBounds.width;
-      const leftPlacementClippedPx = ownBounds.width - left - offsetLeft;
+    if (visualParentBounds.width) {
+      const leftInVisualParent =
+        left +
+        (portalContainerPosition?.left || 0) -
+        (portalContainerPosition ? visualParentBounds.left : 0);
+      const rightPlacementClippedPx =
+        leftInVisualParent + offsetLeft + ownBounds.width - visualParentBounds.width;
+      const leftPlacementClippedPx = ownBounds.width - leftInVisualParent - offsetLeft;
       placeTooltipLeft =
         rightPlacementClippedPx > 0 && rightPlacementClippedPx > leftPlacementClippedPx;
     } else {
@@ -42,9 +62,14 @@ function TooltipWithBounds({
         rightPlacementClippedPx > 0 && rightPlacementClippedPx > leftPlacementClippedPx;
     }
 
-    if (parentBounds.height) {
-      const bottomPlacementClippedPx = top + offsetTop + ownBounds.height - parentBounds.height;
-      const topPlacementClippedPx = ownBounds.height - top - offsetTop;
+    if (visualParentBounds.height) {
+      const topInVisualParent =
+        top +
+        (portalContainerPosition?.top || 0) -
+        (portalContainerPosition ? visualParentBounds.top : 0);
+      const bottomPlacementClippedPx =
+        topInVisualParent + offsetTop + ownBounds.height - visualParentBounds.height;
+      const topPlacementClippedPx = ownBounds.height - topInVisualParent - offsetTop;
       placeTooltipUp =
         bottomPlacementClippedPx > 0 && bottomPlacementClippedPx > topPlacementClippedPx;
     } else {