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
Version 1
Version 2
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,
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