Sensors

useOnLongPress

Detect long press gestures on an element. Fires a handler after a configurable delay, with support for distance thresholds, event modifiers, and a release callback.

Detect long press gestures on an element. Fires a handler callback after a configurable hold duration (default 500ms), with optional distance threshold cancellation, event modifiers, and a release callback.

Demo

useOnLongPress

Idle

Press and hold the box for 500ms to trigger a long press.

Press and hold here

Long Presses

Last Duration

—

import { 
const useRef$: {
    <T = any>(initialValue: null): Ref$<T | null>;
    <T = any>(initialValue: T): Ref$<T>;
    <T = any>(): Ref$<T | null>;
}
useRef$ } from "@usels/core";
import { 
const useOnLongPress: (target: MaybeEventTarget, handler: (evt: PointerEvent) => void, options?: DeepMaybeObservable<UseOnLongPressOptions>) => Fn
useOnLongPress } from "@usels/web";

function 
function Component(): JSX.Element
Component() {
  const 
const el$: Ref$<HTMLDivElement | null>
el$ = 
useRef$<HTMLDivElement>(): Ref$<HTMLDivElement | null> (+2 overloads)
Core (framework-agnostic) version of useRef$.
Creates an observable element ref with opaque wrapping.

non-null value → Ref$<T>: current, get(), peek() return T
null / no arg → Ref$<T | null>: current, get(), peek() return T | null

Nullability is expressed via the type parameter, mirroring T | null at the call site.
useRef$<
interface HTMLDivElement
HTMLDivElement>();

  
function useOnLongPress(target: MaybeEventTarget, handler: (evt: PointerEvent) => void, options?: DeepMaybeObservable<UseOnLongPressOptions>): Fn
Framework-agnostic long press gesture detector.
Listens for pointerdown/pointermove/pointerup/pointerleave events
and fires the handler callback after the configured delay when held.
@param ― target - The element to detect long presses on
@param ― handler - Callback fired when a long press is detected
@param ― options - Configuration options
@returns ― A stop function that removes all event listeners and clears timers
useOnLongPress(
const el$: Ref$<HTMLDivElement | null>
el$, (
e: PointerEvent
e) => {
    
any
console.
any
log("Long pressed!", 
e: PointerEvent
e);
  });

  return <
JSX.IntrinsicElements.div: DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div 
RefAttributes<HTMLDivElement>.ref?: Ref<HTMLDivElement> | undefined
Allows getting a ref to the component instance.
Once the component unmounts, React will set ref.current to null
(or call the ref with null if you passed a callback ref).
@see ― https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs
ref={
const el$: Ref$<HTMLDivElement | null>
el$}>Press and hold me</
JSX.IntrinsicElements.div: DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div>;
}

import { createRef$ } from "@usels/core";
import { createOnLongPress } from "@usels/web";

function Component() {
  "use scope"
  const el$ = createRef$<HTMLDivElement>();

  createOnLongPress(el$, (e) => {
    console.log("Long pressed!", e);
  });

  return <div ref={el$}>Press and hold me</div>;
}

Custom delay

Hook
Scope

import { useRef$ } from "@usels/core";
import { useOnLongPress } from "@usels/web";

function Component() {
  const el$ = useRef$<HTMLDivElement>();
  useOnLongPress(el$, () => {}, { delay: 1000 }); // 1 second
  return <div ref={el$} />;
}

import { createRef$ } from "@usels/core";
import { createOnLongPress } from "@usels/web";

function Component() {
  "use scope"
  const el$ = createRef$<HTMLDivElement>();
  createOnLongPress(el$, () => {}, { delay: 1000 }); // 1 second
  return <div ref={el$} />;
}

Distance threshold

Cancel the long press when the pointer moves too far from the initial position. Default is 10px. Set to false to disable.

Hook
Scope

import { useRef$ } from "@usels/core";
import { useOnLongPress } from "@usels/web";

function Component() {
  const el$ = useRef$<HTMLDivElement>();

  // Custom threshold
  useOnLongPress(el$, () => {}, { distanceThreshold: 20 });

  // Disable distance checking
  useOnLongPress(el$, () => {}, { distanceThreshold: false });

  return <div ref={el$} />;
}

import { createRef$ } from "@usels/core";
import { createOnLongPress } from "@usels/web";

function Component() {
  "use scope"
  const el$ = createRef$<HTMLDivElement>();

  // Custom threshold
  createOnLongPress(el$, () => {}, { distanceThreshold: 20 });

  // Disable distance checking
  createOnLongPress(el$, () => {}, { distanceThreshold: false });

  return <div ref={el$} />;
}

Release callback (onMouseUp)

onMouseUp is called when the pointer is released, providing duration, distance, and whether a long press was detected.

Hook
Scope

import { useRef$ } from "@usels/core";
import { useOnLongPress } from "@usels/web";

function Component() {
  const el$ = useRef$<HTMLDivElement>();

  useOnLongPress(el$, () => {}, {
    onMouseUp: (duration, distance, isLongPress, event) => {
      if (isLongPress) {
        console.log(`Long press released after ${duration}ms`);
      } else {
        console.log(`Short press: ${duration}ms`);
      }
    },
  });

  return <div ref={el$} />;
}

import { createRef$ } from "@usels/core";
import { createOnLongPress } from "@usels/web";

function Component() {
  "use scope"
  const el$ = createRef$<HTMLDivElement>();

  createOnLongPress(el$, () => {}, {
    onMouseUp: (duration, distance, isLongPress, event) => {
      if (isLongPress) {
        console.log(`Long press released after ${duration}ms`);
      } else {
        console.log(`Short press: ${duration}ms`);
      }
    },
  });

  return <div ref={el$} />;
}

Event modifiers

Hook
Scope

import { useRef$ } from "@usels/core";
import { useOnLongPress } from "@usels/web";

function Component() {
  const el$ = useRef$<HTMLDivElement>();

  useOnLongPress(el$, () => {}, {
    modifiers: {
      prevent: true,  // preventDefault on pointer events
      stop: true,     // stopPropagation
      self: true,     // only trigger on the element itself (not children)
      capture: true,  // use capturing phase
      once: true,     // fire only once
    },
  });

  return <div ref={el$} />;
}

import { createRef$ } from "@usels/core";
import { createOnLongPress } from "@usels/web";

function Component() {
  "use scope"
  const el$ = createRef$<HTMLDivElement>();

  createOnLongPress(el$, () => {}, {
    modifiers: {
      prevent: true,  // preventDefault on pointer events
      stop: true,     // stopPropagation
      self: true,     // only trigger on the element itself (not children)
      capture: true,  // use capturing phase
      once: true,     // fire only once
    },
  });

  return <div ref={el$} />;
}

Stop function

useOnLongPress returns a stop function to manually remove all listeners and clear timers.

Hook
Scope

import { useRef$ } from "@usels/core";
import { useOnLongPress } from "@usels/web";

function Component() {
  const el$ = useRef$<HTMLDivElement>();
  const stop = useOnLongPress(el$, () => {});

  // Later: remove all listeners
  stop();

  return <div ref={el$} />;
}

import { createRef$ } from "@usels/core";
import { createOnLongPress } from "@usels/web";

function Component() {
  "use scope"
  const el$ = createRef$<HTMLDivElement>();
  const stop = createOnLongPress(el$, () => {});

  // Later: remove all listeners
  stop();

  return <div ref={el$} />;
}

Type

Parameters

Parameter	Type	Description
`target`	`MaybeEventTarget`	- The element to detect long presses on
`handler`	`(evt: PointerEvent) => void`	- Callback fired when a long press is detected
`options`	`UseOnLongPressOptions` (optional)	- Configuration options

UseOnLongPressOptions

Option	Type	Default	Description
`delay`	`number`	`500`	Time in ms till `longpress` gets called
`distanceThreshold`	`number \| false`	`10`	Allowance of moving distance in pixels. The action will get canceled when moving too far from the pointerdown position. Set to `false` to disable distance checking.
`modifiers`	`UseOnLongPressModifiers`	`-`	Event modifiers
`onMouseUp`	`((duration: number, distance: number, isLongPress: boolean, event: PointerEvent) => void)`	`-`	Function called when the element is released.

Returns

Fn

A stop function that removes all event listeners and clears timers

Source

View on GitHub