react-use-hoverintent

1.3.0 verified Fri May 01 auth: no javascript

React hook that implements hoverIntent behavior, delaying hover callbacks until the user's mouse slows down. Version 1.3.0 supports ESM and CommonJS, includes TypeScript types, and has zero dependencies. Released roughly every few months with maintenance updates. Differentiates from alternatives by being a lightweight hook with no external runtime requirements, inspired by jQuery hoverIntent.

Common errors

error TypeError: can't access property 'current', intentRef is undefined ↓

cause Calling useHoverIntent outside a React functional component or before component mount.

fix

Ensure useHoverIntent is called inside a React functional component. Check that intentRef is correctly destructured: const [isHovering, intentRef] = useHoverIntent();

error Warning: Function components cannot be given refs. Attempts to access this ref will fail. ↓

cause Using intentRef on a custom component without forwardRef.

fix

Use React.forwardRef on custom components and pass intentRef to the underlying DOM element.

error useHoverIntent is not a function or its return value is iterable ↓

cause Importing default import instead of named import.

fix

Use import { useHoverIntent } from 'react-use-hoverintent'

Warnings

breaking v1.2.9 reversed the array return order to match earlier versions, potentially breaking code that depended on v1.2.8's order. ↓

fix Upgrade to v1.2.9+ and ensure array destructuring order matches documentation: [isHovering, intentRef, setIsHovering]

gotcha The setIsHovering setter exposed since v1.2.8 allows direct mutation of hover state, which can desync from actual mouse events. ↓

fix Avoid using setIsHovering unless absolutely necessary; prefer relying on hover intent callbacks.

gotcha Using ref option with forwarded refs requires careful merging to avoid losing the original ref binding. ↓

fix Pass ref option to useHoverIntent({ref: forwardedRef}) and ensure intentRef is used on DOM element.

Install

npm install react-use-hoverintent

yarn add react-use-hoverintent

pnpm add react-use-hoverintent

Imports

useHoverIntent

wrong

import useHoverIntent from 'react-use-hoverintent'

correct

import { useHoverIntent } from 'react-use-hoverintent'

Named export only. ESM module available via .esm.js path from v1.3.0.

Quickstart

Basic usage of useHoverIntent hook with custom options, showing isHovering state and ref.

import { useHoverIntent } from 'react-use-hoverintent';
import React from 'react';

export const MyComponent = () => {
  const [isHovering, intentRef, setIsHovering] = useHoverIntent({
    timeout: 150,
    sensitivity: 7,
    interval: 120
  });
  return (
    <div
      ref={intentRef}
      style={{
        width: 200,
        height: 200,
        background: isHovering ? 'blue' : 'gray',
        transition: 'background 0.3s'
      }}
    >
      {isHovering ? 'Hovering' : 'Not hovering'}
    </div>
  );
};