useHover

sensors

Installation

npx usehooks-cli@latest add use-hover

Description

A React hook for detecting when an element is being hovered with optional callbacks, delay support, and TypeScript generics for element types.

Parameters

Name	Type	Default	Description
options?	UseHoverOptions	{}	Configuration options for hover behavior

Return Type

UseHoverReturn<T>

Property	Type	Description
isHovered	boolean	Whether the element is currently being hovered
ref	React.RefObject<T>	Ref to attach to the element you want to detect hover on

Examples

Basic Hover Detection

Simple hover state detection

const { isHovered, ref } = useHover();

return (
  <div
    ref={ref}
    style={{
      padding: '20px',
      backgroundColor: isHovered ? 'lightblue' : 'lightgray'
    }}
  >
    {isHovered ? 'Hovered!' : 'Hover me'}
  </div>
);

With Callbacks and Delay

Using hover with callbacks and delay

const { isHovered, ref } = useHover({
  onHoverStart: () => console.log('Hover started'),
  onHoverEnd: () => console.log('Hover ended'),
  delay: 300 // 300ms delay
});

return (
  <button ref={ref}>
    {isHovered ? 'Hovering...' : 'Hover me (with delay)'}
  </button>
);

Dependencies

react

Notes

•Automatically cleans up event listeners on unmount
•Supports delay for hover start but immediate hover end
•Uses TypeScript generics for type-safe element references
•Handles timeout cleanup to prevent memory leaks

Implementation

'use client';

import { useState, useCallback, useRef, useEffect } from "react";

interface UseHoverOptions {
  onHoverStart?: () => void;
  onHoverEnd?: () => void;
  delay?: number;
}

interface UseHoverReturn<T extends HTMLElement = HTMLElement> {
  isHovered: boolean;
  ref: React.RefObject<T>;
}

export const useHover = <T extends HTMLElement = HTMLElement>(
  options: UseHoverOptions = {}
): UseHoverReturn<T> => {
  const [isHovered, setIsHovered] = useState(false);
  const ref = useRef<T>(null);
  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);

  const { onHoverStart, onHoverEnd, delay = 0 } = options;

  const handleMouseEnter = useCallback(() => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
      timeoutRef.current = null;
    }

    if (delay > 0) {
      timeoutRef.current = setTimeout(() => {
        setIsHovered(true);
        onHoverStart?.();
      }, delay);
    } else {
      setIsHovered(true);
      onHoverStart?.();
    }
  }, [onHoverStart, delay]);

  const handleMouseLeave = useCallback(() => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
      timeoutRef.current = null;
    }

    setIsHovered(false);
    onHoverEnd?.();
  }, [onHoverEnd]);

  useEffect(() => {
    const element = ref.current;
    if (!element) return;

    element.addEventListener("mouseenter", handleMouseEnter);
    element.addEventListener("mouseleave", handleMouseLeave);

    return () => {
      element.removeEventListener("mouseenter", handleMouseEnter);
      element.removeEventListener("mouseleave", handleMouseLeave);

      if (timeoutRef.current) {
        clearTimeout(timeoutRef.current);
      }
    };
  }, [handleMouseEnter, handleMouseLeave]);

  // Cleanup timeout on unmount
  useEffect(() => {
    return () => {
      if (timeoutRef.current) {
        clearTimeout(timeoutRef.current);
      }
    };
  }, []);

  return {
    isHovered,
    ref: ref as React.RefObject<T>,
  };
};

useGeolocation

CLI Docs All Hooks

useIsMobile