use-long-press

React Long Press Hook :point_down:

React hook for detecting click (or tap) and hold event.

• Easy to use
• Highly customizable options
• Thoroughly tested

Install

yarn add use-long-press

or

npm install --save use-long-press

Basic Usage

import React from 'react';
import { useLongPress } from 'use-long-press';

const Example = () => {
  const bind = useLongPress(() => {
    console.log('Long pressed!');
  });

  return <button {...bind()}>Press me</button>;
};

Live example (v1)

Advanced usage

Hook first parameter, callback, can be either function or null (if you want to disable the hook).

Additionally, you can supply options object as a second parameter.

As a result hook returns object with various handlers (depending on detect option), which can be spread to some element.

You can supply custom context to the bind function like bind(context) and then access it from callbacks (onStart, onFinish, onCancel, onMove) second argument e.g.: onStart: (event, { context }) => ....

Definition

useLongPress(callback [, options]): handlers

Options

Long press hook can be adjusted using options object, which allow you to fit it to your needs.

Name	Type	Default	Description
threshold	number	400	Time user need to hold click or tap before long press callback is triggered
captureEvent	boolean	false	If React MouseEvent (or TouchEvent) should be supplied as first argument to callbacks
detect	Enum('mouse' | 'touch' | 'both')	'both'	Which event handlers should be returned in bind object. In TS this enum is accessible through LongPressDetectEvents
cancelOnMovement	boolean | number	false	If long press should be cancelled when detected movement while pressing. Use boolean value to turn it on / off or number value to specify move tolerance in pixels. For more information on how this prop work check JSDoc.
filterEvents	(event) => boolean	undefined	If provided, it gives you the ability to ignore long press detection on specified conditions (for example on right mouse click). When function returns false, it will prevent ANY callbacks from triggering (including onStart and onCancel) as well as capturing event.
onStart	Function	undefined	Called when element is initially pressed (before starting timer which detects long press). Can accept mouse or touch event if captureEvents option is set to true.
onFinish	Function	undefined	Called when press is released (after triggering callback). Can accept mouse or touch event if captureEvents option is set to true.
onCancel	Function	undefined	Called when press is released before threshold time elapses, therefore before long press occurs. Can accept mouse or touch event if captureEvents option is set to true. You can obtain reason for cancellation from a second callback argument e.g.: onCancel: (event, { reason }) => ...
onMove	Function	undefined	Handler for onTouchMove and onMouseMove props, also allowing to make some operations on event before triggering cancelOnMovement. Can accept mouse or touch event if captureEvents option is set to true.

Example

import React, { useState, useCallback } from 'react';
import { useLongPress } from 'use-long-press';

export default function AdvancedExample() {
  const [enabled, setEnabled] = useState(true);
  const callback = useCallback(event => {
    alert('Long pressed!');
  }, []);
  const bind = useLongPress(enabled ? callback : null, {
    onStart: event => console.log('Press started'),
    onFinish: event => console.log('Long press finished'),
    onCancel: event => console.log('Press cancelled'),
    onMove: event => console.log('Detected mouse or touch movement'),
    filterEvents: event => true, // All events can potentially trigger long press
    threshold: 500,
    captureEvent: true,
    cancelOnMovement: false,
    detect: 'both',
  });

  return (
    <div>
      <button {...bind()}>Press and hold</button>
      <div>
        <label htmlFor="enabled">
          <input type="checkbox" id="enabled" checked={enabled} onChange={() => setEnabled(current => !current)} />
          Hook enabled
        </label>
      </div>
    </div>
  );
}

License

MIT © minwork