EventIntermediateBrowser APIshooks/events/useLongPress.ts

useLongPress

Long-press gesture for mouse and touch.

Import

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

API

Signature

useLongPress(onLongPress, options?) → handlers

When to use

Use useLongPress 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 · useLongPress
Editor
function Tile() {
  const bind = useLongPress(() => alert('long press'), { delay: 500 });
  return <button {...bind}>Hold me</button>;
}
Preview

Implementation source

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

hooks/events/useLongPress.ts
import { useCallback, useRef } from 'react';
import { useLatest } from '../utility/useLatest';

export interface UseLongPressOptions {
  delay?: number;
  onStart?: (event: React.MouseEvent | React.TouchEvent) => void;
  onFinish?: (event: React.MouseEvent | React.TouchEvent) => void;
  onCancel?: (event: React.MouseEvent | React.TouchEvent) => void;
  moveThreshold?: number;
}

/** Long-press gesture handlers (mouse + touch). */
export function useLongPress(
  onLongPress: (event: React.MouseEvent | React.TouchEvent) => void,
  options: UseLongPressOptions = {},
) {
  const {
    delay = 500,
    onStart,
    onFinish,
    onCancel,
    moveThreshold = 10,
  } = options;
  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
  const startPos = useRef<{ x: number; y: number } | null>(null);
  const pressed = useRef(false);
  const onLongPressRef = useLatest(onLongPress);
  const onStartRef = useLatest(onStart);
  const onFinishRef = useLatest(onFinish);
  const onCancelRef = useLatest(onCancel);

  const clear = useCallback(() => {
    if (timer.current) {
      clearTimeout(timer.current);
      timer.current = null;
    }
  }, []);

  const start = useCallback(
    (event: React.MouseEvent | React.TouchEvent) => {
      const point =
        'touches' in event
          ? { x: event.touches[0]?.clientX ?? 0, y: event.touches[0]?.clientY ?? 0 }
          : { x: event.clientX, y: event.clientY };
      startPos.current = point;
      pressed.current = false;
      onStartRef.current?.(event);
      clear();
      timer.current = setTimeout(() => {
        pressed.current = true;
        onLongPressRef.current(event);
        onFinishRef.current?.(event);
      }, delay);
    },
    [clear, delay, onLongPressRef, onStartRef, onFinishRef],
  );

  const move = useCallback(
    (event: React.MouseEvent | React.TouchEvent) => {
      if (!startPos.current) return;
      const point =
        'touches' in event
          ? { x: event.touches[0]?.clientX ?? 0, y: event.touches[0]?.clientY ?? 0 }
          : { x: event.clientX, y: event.clientY };
      const dx = Math.abs(point.x - startPos.current.x);
      const dy = Math.abs(point.y - startPos.current.y);
      if (dx > moveThreshold || dy > moveThreshold) {
        clear();
        if (!pressed.current) onCancelRef.current?.(event);
        startPos.current = null;
      }
    },
    [clear, moveThreshold, onCancelRef],
  );

  const end = useCallback(
    (event: React.MouseEvent | React.TouchEvent) => {
      clear();
      if (!pressed.current) onCancelRef.current?.(event);
      startPos.current = null;
    },
    [clear, onCancelRef],
  );

  return {
    onMouseDown: start,
    onTouchStart: start,
    onMouseMove: move,
    onTouchMove: move,
    onMouseUp: end,
    onMouseLeave: end,
    onTouchEnd: end,
  };
}

Copy-paste example

useLongPress.example.tsx
'use client';

import { useLongPress } from '@/hooks';

export function Tile() {
  const bind = useLongPress(() => alert('long press'), { delay: 500 });
  return <button {...bind}>Hold me</button>;
}

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/useLongPress.ts for implementation details