# useLongPress



## Features

A long press is triggered when a user presses and holds their pointer over a target for a minimum period of time. If the user moves their pointer off of the target before the time threshold, the interaction is canceled. Once a long press event is triggered, other pointer interactions that may be active such as `usePress` and `useMove` will be canceled so that only the long press is activated.

* Handles mouse and touch events
* Uses pointer events where available, with fallbacks to mouse and touch events
* Ignores emulated mouse events in mobile browsers
* Prevents text selection on touch devices while long pressing
* Prevents browser and OS context menus from appearing while long pressing
* Customizable time threshold for long press
* Supports an accessibility description to indicate to assistive technology users that a long press action is available

## Example

This example shows a button that has both a normal press action using [usePress](usePress.md), as well as a long
press action using `useLongPress`. Pressing the button will set the mode to "Normal speed", and long pressing it will
set the mode to "Hyper speed". All of the emitted events are also logged below. Note that when long pressing the button,
only a long press is emitted, and no normal press is emitted on pointer up.

**Note**: this example does not have a keyboard accessible way to trigger the long press action. Because the method of triggering
this action will differ depending on the component, it is outside the scope of `useLongPress`. Make sure to implement a keyboard
friendly alternative to all long press interactions if you are using this hook directly.

```tsx
import React from 'react';
import {mergeProps} from '@react-aria/utils';
import {useLongPress, usePress} from '@react-aria/interactions';

function Example() {
  let [events, setEvents] = React.useState([]);
  let [mode, setMode] = React.useState('Activate');
  let {longPressProps} = useLongPress({
    accessibilityDescription: 'Long press to activate hyper speed',
    onLongPressStart: e => setEvents(
      events => [`long press start with ${e.pointerType}`, ...events]
    ),
    onLongPressEnd: e => setEvents(
      events => [`long press end with ${e.pointerType}`, ...events]
    ),
    onLongPress: e => {
      setMode('Hyper speed');
      setEvents(
        events => [`long press with ${e.pointerType}`, ...events]
      );
    }
  });

  let {pressProps} = usePress({
    onPress: e => {
      setMode('Normal speed');
      setEvents(
        events => [`press with ${e.pointerType}`, ...events]
      );
    }
  });

  return (
    <>
      <button {...mergeProps(pressProps, longPressProps)}>{mode}</button>
      <ul
        style={{
          maxHeight: '200px',
          overflow: 'auto'
        }}>
        {events.map((e, i) => <li key={i}>{e}</li>)}
      </ul>
    </>
  );
}
```

## API

<FunctionAPI
  function={docs.exports.useLongPress}
  links={docs.links}
/>

### LongPressProps

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `isDisabled` | `boolean | undefined` | — | Whether long press events should be disabled. |
| `onLongPressStart` | `((e: LongPressEvent) => void) | undefined` | — | Handler that is called when a long press interaction starts. |
| `onLongPressEnd` | `((e: LongPressEvent) => void) | undefined` | — | Handler that is called when a long press interaction ends, either over the target or when the pointer leaves the target. |
| `onLongPress` | `((e: LongPressEvent) => void) | undefined` | — | Handler that is called when the threshold time is met while the press is over the target. |
| `threshold` | `number | undefined` | 500ms | The amount of time in milliseconds to wait before triggering a long press. |
| `accessibilityDescription` | `string | undefined` | — | A description for assistive techology users indicating that a long press action is available, e.g. "Long press to open menu". |

### LongPressResult

| Name | Type | Description |
|------|------|-------------|
| `longPressProps` \* | `DOMAttributes<FocusableElement>` | Props to spread on the target element. |

### LongPressEvent

Each of these handlers is fired with a `LongPressEvent`, which exposes information about the target and the
type of event that triggered the interaction.