feat: add autoClose prop and logic

Author: danielbarion

docs/docs/options.mdx

@@ -66,6 +66,7 @@ import { Tooltip } from 'react-tooltip';
 | data-tooltip-position-strategy | string     | false     | `absolute`  | `absolute` `fixed`                                                                                                                | The position strategy used for the tooltip. Set to `fixed` if you run into issues with `overflow: hidden` on the tooltip parent container |
 | data-tooltip-delay-show        | number     | false     |             | any `number`                                                                                                                      | The delay (in ms) before showing the tooltip                                                                                              |
 | data-tooltip-delay-hide        | number     | false     |             | any `number`                                                                                                                      | The delay (in ms) before hiding the tooltip                                                                                               |
+| data-tooltip-auto-close        | number     | false     |             | any positive `number`                                                                                                             | Automatically closes the tooltip after the given time (in ms), even if the anchor is still hovered                                       |
 | data-tooltip-float             | boolean    | false     | `false`     | `true` `false`                                                                                                                    | Tooltip will follow the mouse position when it moves inside the anchor element (same as V4's `effect="float"`)                            |
 | data-tooltip-hidden            | boolean    | false     | `false`     | `true` `false`                                                                                                                    | Tooltip will not be shown                                                                                                                 |
 | data-tooltip-class-name        | string     | false     |             |                                                                                                                                   | Classnames for the tooltip container                                                                                                      |
@@ -107,6 +108,7 @@ import { Tooltip } from 'react-tooltip';
 | `positionStrategy`      | `string`                   | no       | `absolute`          | `absolute` `fixed`                                                                                                                | The position strategy used for the tooltip. Set to `fixed` if you run into issues with `overflow: hidden` on the tooltip parent container                       |
 | `delayShow`             | `number`                   | no       |                     | any `number`                                                                                                                      | The delay (in ms) before showing the tooltip                                                                                                                    |
 | `delayHide`             | `number`                   | no       |                     | any `number`                                                                                                                      | The delay (in ms) before hiding the tooltip                                                                                                                     |
+| `autoClose`             | `number`                   | no       |                     | any positive `number`                                                                                                             | Automatically closes the tooltip after the given time (in ms). When the active anchor changes, the timer starts again for the new anchor |
 | `float`                 | `boolean`                  | no       | `false`             | `true` `false`                                                                                                                    | Tooltip will follow the mouse position when it moves inside the anchor element (same as V4's `effect="float"`)                                                  |
 | `hidden`                | `boolean`                  | no       | `false`             | `true` `false`                                                                                                                    | Tooltip will not be shown                                                                                                                                       |
 | `noArrow`               | `boolean`                  | no       | `false`             | `true` `false`                                                                                                                    | Tooltip arrow will not be shown                                                                                                                                 |

docs/docs/upgrade-guide/changelog-v5-v6.md

@@ -14,6 +14,7 @@ V6 keeps the core tooltip behavior from V5, but updates the implementation and A
 - runtime behavior is lighter and more scalable in larger interfaces
 - React 19 is supported while React 16.14+ remains compatible
 - optional `portalRoot` support lets you render the tooltip into a custom DOM container when you need tighter control over clipping and overlay layout
+- optional `autoClose` support lets a tooltip dismiss itself after a fixed visible duration without custom timeout wiring
 
 ## Breaking Changes
 
@@ -25,6 +26,7 @@ V6 keeps the core tooltip behavior from V5, but updates the implementation and A
 
 - `children` and `render` are the preferred way to render rich tooltip content in v6
 - `portalRoot` is available when the tooltip should render into a specific DOM node, such as `document.body`
+- `autoClose` is available when a tooltip should close after a fixed delay, including cases where the pointer is still over the anchor
 - v6 includes internal runtime improvements that reduce mount cost, memory retention, and shipped bundle size relative to v5
 
 ## `portalRoot`
@@ -44,6 +46,16 @@ When a layout clips overlays or makes stacking difficult, you can render the too
 
 When portaling to `document.body`, `positionStrategy="fixed"` is the safest default because it avoids most coordinate-space and overflow issues.
 
+## `autoClose`
+
+If a tooltip should remain visible only for a fixed amount of time, you can let the component close itself:
+
+```jsx
+<Tooltip id="my-tooltip" content="Hello" autoClose={5000} />
+```
+
+This is useful when the tooltip should dismiss after a short reading window even if the user keeps hovering the same anchor. When the active anchor changes, the timer starts again for the newly active anchor.
+
 ## What should I use instead?
 
 ### Replace `data-tooltip-html` with tooltip `children`
@@ -97,5 +109,6 @@ If you previously used HTML strings for multiline tooltips, render JSX instead:
 - `content` is still supported for plain string content
 - `children` and `render` are now the recommended way to display rich tooltip content
 - `portalRoot` is optional and only needed when you want the tooltip rendered outside its default location
+- `autoClose` is optional and only needed when the tooltip should dismiss itself after a fixed visible duration
 
 Check the current examples for [children](../examples/children.mdx), [render](../examples/render.mdx), and [multiline content](../examples/multiline.mdx).

docs/versioned_docs/version-5.x/upgrade-guide/changelog-v5-v6.md

@@ -14,6 +14,7 @@ V6 keeps the core tooltip behavior from V5, but updates the implementation and A
 - runtime behavior is lighter and more scalable in larger interfaces
 - React 19 is supported while React 16.14+ remains compatible
 - optional `portalRoot` support lets you render the tooltip into a custom DOM container when you need tighter control over clipping and overlay layout
+- optional `autoClose` support lets a tooltip dismiss itself after a fixed visible duration without custom timeout wiring
 
 ## Breaking Changes
 
@@ -25,6 +26,7 @@ V6 keeps the core tooltip behavior from V5, but updates the implementation and A
 
 - `children` and `render` are the preferred way to render rich tooltip content in v6
 - `portalRoot` is available when the tooltip should render into a specific DOM node, such as `document.body`
+- `autoClose` is available when a tooltip should close after a fixed delay, including cases where the pointer is still over the anchor
 - v6 includes internal runtime improvements that reduce mount cost, memory retention, and shipped bundle size relative to v5
 
 ## `portalRoot`
@@ -44,6 +46,16 @@ When a layout clips overlays or makes stacking difficult, you can render the too
 
 When portaling to `document.body`, `positionStrategy="fixed"` is the safest default because it avoids most coordinate-space and overflow issues.
 
+## `autoClose`
+
+If a tooltip should remain visible only for a fixed amount of time, you can let the component close itself:
+
+```jsx
+<Tooltip id="my-tooltip" content="Hello" autoClose={5000} />
+```
+
+This is useful when the tooltip should dismiss after a short reading window even if the user keeps hovering the same anchor. When the active anchor changes, the timer starts again for the newly active anchor.
+
 ## What should I use instead?
 
 ### Replace `data-tooltip-html` with tooltip `children`
@@ -97,5 +109,6 @@ If you previously used HTML strings for multiline tooltips, render JSX instead:
 - `content` is still supported for plain string content
 - `children` and `render` are now the recommended way to display rich tooltip content
 - `portalRoot` is optional and only needed when you want the tooltip rendered outside its default location
+- `autoClose` is optional and only needed when the tooltip should dismiss itself after a fixed visible duration
 
 Check the current examples for [children](../examples/children.mdx), [render](../examples/render.mdx), and [multiline content](../examples/multiline.mdx).

src/components/Tooltip/Tooltip.tsx

@@ -32,6 +32,7 @@ const Tooltip = ({
   wrapper: WrapperElement,
   delayShow = 0,
   delayHide = 0,
+  autoClose,
   float = false,
   hidden = false,
   noArrow = false,
@@ -64,6 +65,7 @@ const Tooltip = ({
   const tooltipArrowRef = useRef<HTMLElement>(null)
   const tooltipShowDelayTimerRef = useRef<NodeJS.Timeout | null>(null)
   const tooltipHideDelayTimerRef = useRef<NodeJS.Timeout | null>(null)
+  const tooltipAutoCloseTimerRef = useRef<NodeJS.Timeout | null>(null)
   const missedTransitionTimerRef = useRef<NodeJS.Timeout | null>(null)
   const [computedPosition, setComputedPosition] = useState<IComputedPosition>({
     tooltipStyles: {},
@@ -199,6 +201,24 @@ const Tooltip = ({
     }
   }, [afterHide, afterShow, show])
 
+  useEffect(() => {
+    clearTimeoutRef(tooltipAutoCloseTimerRef)
+
+    if (!show || !autoClose || autoClose <= 0) {
+      return () => {
+        clearTimeoutRef(tooltipAutoCloseTimerRef)
+      }
+    }
+
+    tooltipAutoCloseTimerRef.current = setTimeout(() => {
+      handleShow(false)
+    }, autoClose)
+
+    return () => {
+      clearTimeoutRef(tooltipAutoCloseTimerRef)
+    }
+  }, [activeAnchor, autoClose, handleShow, show])
+
   const handleComputedPosition = useCallback((newComputedPosition: IComputedPosition) => {
     if (!mounted.current) {
       return
@@ -353,6 +373,7 @@ const Tooltip = ({
     setActiveAnchor(null)
     clearTimeoutRef(tooltipShowDelayTimerRef)
     clearTimeoutRef(tooltipHideDelayTimerRef)
+    clearTimeoutRef(tooltipAutoCloseTimerRef)
   }, [handleShow, setActiveAnchor])
 
   const anchorElements = useTooltipAnchors({
@@ -456,6 +477,7 @@ const Tooltip = ({
     return () => {
       clearTimeoutRef(tooltipShowDelayTimerRef)
       clearTimeoutRef(tooltipHideDelayTimerRef)
+      clearTimeoutRef(tooltipAutoCloseTimerRef)
       clearTimeoutRef(missedTransitionTimerRef)
     }
   }, [defaultIsOpen, handleShow])
@@ -519,6 +541,7 @@ const Tooltip = ({
       // Final cleanup to ensure no memory leaks
       clearTimeoutRef(tooltipShowDelayTimerRef)
       clearTimeoutRef(tooltipHideDelayTimerRef)
+      clearTimeoutRef(tooltipAutoCloseTimerRef)
       clearTimeoutRef(missedTransitionTimerRef)
     }
   }, [])

src/components/Tooltip/TooltipTypes.d.ts

@@ -29,6 +29,7 @@ export type DataAttribute =
   | 'position-strategy'
   | 'delay-show'
   | 'delay-hide'
+  | 'auto-close'
   | 'float'
   | 'hidden'
   | 'class-name'
@@ -112,6 +113,7 @@ export interface ITooltip {
   middlewares?: Middleware[]
   delayShow?: number
   delayHide?: number
+  autoClose?: number
   float?: boolean
   hidden?: boolean
   noArrow?: boolean

src/components/TooltipController/TooltipController.tsx

@@ -32,6 +32,7 @@ const TooltipController = React.forwardRef<TooltipRefProps, ITooltipController>(
       middlewares,
       delayShow = 0,
       delayHide = 0,
+      autoClose,
       float = false,
       hidden = false,
       noArrow = false,
@@ -182,6 +183,10 @@ const TooltipController = React.forwardRef<TooltipRefProps, ITooltipController>(
       anchorDataAttributes['delay-hide'] == null
         ? delayHide
         : Number(anchorDataAttributes['delay-hide'])
+    const tooltipAutoClose =
+      anchorDataAttributes['auto-close'] == null
+        ? autoClose
+        : Number(anchorDataAttributes['auto-close'])
     const tooltipFloat =
       anchorDataAttributes.float == null ? float : anchorDataAttributes.float === 'true'
     const tooltipHidden =
@@ -220,6 +225,7 @@ const TooltipController = React.forwardRef<TooltipRefProps, ITooltipController>(
       middlewares,
       delayShow: tooltipDelayShow,
       delayHide: tooltipDelayHide,
+      autoClose: tooltipAutoClose,
       float: tooltipFloat,
       hidden: tooltipHidden,
       noArrow,

src/components/TooltipController/TooltipControllerTypes.d.ts

@@ -30,6 +30,7 @@ export interface ITooltipController {
   middlewares?: Middleware[]
   delayShow?: number
   delayHide?: number
+  autoClose?: number
   float?: boolean
   hidden?: boolean
   noArrow?: boolean
@@ -84,6 +85,7 @@ declare module 'react' {
     'data-tooltip-position-strategy'?: PositionStrategy
     'data-tooltip-delay-show'?: number
     'data-tooltip-delay-hide'?: number
+    'data-tooltip-auto-close'?: number
     'data-tooltip-float'?: boolean
     'data-tooltip-hidden'?: boolean
     'data-tooltip-class-name'?: string

src/test/tooltip-close-and-delay-behavior.spec.js

@@ -260,6 +260,55 @@ describe('tooltip close and delay behavior', () => {
     expect(document.getElementById('rehydrated-hide-delay-test')).toBeInTheDocument()
   })
 
+  test('closes automatically after the configured time while still hovering the anchor', async () => {
+    render(
+      <>
+        <span data-tooltip-id="auto-close-test">Hover Me</span>
+        <TooltipController id="auto-close-test" content="Auto Close Test" autoClose={5000} />
+      </>,
+    )
+
+    const anchor = screen.getByText('Hover Me')
+
+    hoverAnchor(anchor, 100)
+    await waitForTooltip('auto-close-test')
+
+    advanceTimers(4900)
+    expect(document.getElementById('auto-close-test')).toBeInTheDocument()
+
+    advanceTimers(200)
+    await waitForTooltipToClose('auto-close-test')
+  })
+
+  test('restarts the auto-close timer when the active anchor changes', async () => {
+    render(
+      <>
+        <span data-tooltip-id="auto-close-reset-test">First Anchor</span>
+        <span data-tooltip-id="auto-close-reset-test">Second Anchor</span>
+        <TooltipController
+          id="auto-close-reset-test"
+          content="Auto Close Reset Test"
+          autoClose={5000}
+        />
+      </>,
+    )
+
+    const firstAnchor = screen.getByText('First Anchor')
+    const secondAnchor = screen.getByText('Second Anchor')
+
+    hoverAnchor(firstAnchor, 100)
+    await waitForTooltip('auto-close-reset-test')
+
+    advanceTimers(3000)
+    hoverAnchor(secondAnchor, 100)
+
+    advanceTimers(3000)
+    expect(document.getElementById('auto-close-reset-test')).toBeInTheDocument()
+
+    advanceTimers(2200)
+    await waitForTooltipToClose('auto-close-reset-test')
+  })
+
   test('cancels a pending show timer when the anchor hides first', () => {
     render(
       <>