EventIntermediateBrowser APIshooks/events/useHover.ts

useHover

Track hover over an element.

Import

TypeScript
import { useHover } from '@/hooks';

API

Signature

useHover(ref) → boolean

When to use

Use useHover instead of re-implementing the same pattern in multiple components.

SSR / Next.js

No-ops until document/window exist.

Live playground

Edit the example and see it run against the real @/hooks package in this app.

Live playgroundEdit · run with real @/hooks · useHover
Editor
function Tip() {
  const ref = useRef<HTMLDivElement>(null);
  const hovered = useHover(ref);
  return <div ref={ref}>{hovered ? 'Hovering' : 'Idle'}</div>;
}
Preview

Implementation source

Full library source for useHover — copy into your project when you are not installing a package yet.

hooks/events/useHover.ts
import { useCallback, useState } from 'react';
import type { RefObject } from 'react';
import { useEventListener } from './useEventListener';

/** Tracks hover state for an element. */
export function useHover<T extends HTMLElement>(
  ref: RefObject<T | null>,
  options: { enabled?: boolean } = {},
): boolean {
  const [hovered, setHovered] = useState(false);
  const { enabled = true } = options;

  useEventListener('mouseenter', () => setHovered(true), ref, { enabled });
  useEventListener('mouseleave', () => setHovered(false), ref, { enabled });

  return hovered;
}

/** Bind-style hover without a ref: returns handlers + state. */
export function useHoverBind(): {
  hovered: boolean;
  bind: {
    onMouseEnter: () => void;
    onMouseLeave: () => void;
  };
} {
  const [hovered, setHovered] = useState(false);
  return {
    hovered,
    bind: {
      onMouseEnter: useCallback(() => setHovered(true), []),
      onMouseLeave: useCallback(() => setHovered(false), []),
    },
  };
}

Copy-paste example

useHover.example.tsx
'use client';

import { useRef } from 'react';
import { useHover } from '@/hooks';

export function Tip() {
  const ref = useRef<HTMLDivElement>(null);
  const hovered = useHover(ref);
  return <div ref={ref}>{hovered ? 'Hovering' : 'Idle'}</div>;
}

Production checklist

  • Called only from Client Components or other custom hooks
  • Type parameters filled in (e.g. useFetch<User[]>)
  • Tip: Pass all relevant refs to useClickOutside (trigger + panel). Prefer useLatest for handlers.
  • Source of truth: open hooks/events/useHover.ts for implementation details