usePress

Handles press interactions across mouse, touch, keyboard, and screen readers. It normalizes behavior across browsers and platforms, and handles many nuances of dealing with pointer and keyboard events.

API

usePress(props: PressHookProps):

Features

usePress handles press interactions across mouse, touch, keyboard, and screen readers. A press interaction starts when a user presses down with a mouse or their finger on the target, and ends when they move the pointer off the target. It may start again if the pointer re-enters the target. usePress returns the current press state, which can be used to adjust the visual appearance of the target. If the pointer is released over the target, then an onPress event is fired.

Handles mouse and touch events
Handles Enter or Space key presses
Handles screen reader virtual clicks
Uses pointer events where available, with fallbacks to mouse and touch events
Normalizes focus behavior on mouse and touch interactions across browsers
Handles disabling text selection on mobile while the press interaction is active
Handles canceling press interactions on scroll
Normalizes many cross browser inconsistencies

Usage

usePress returns props that you should spread onto the target element, along with the current press state:

Name	Type
`pressProps`
Props to spread on the target element.
`isPressed`	`boolean`
Whether the target is currently pressed.

usePress supports the following event handlers:

Name	Type
`onClick`	`(e: MouseEvent<FocusableElement>) => void`
Not recommended – use `onPress` instead. `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides additional event details for non-mouse interactions.
`onPressUp`	`(e: ) => void`
Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`onPressChange`	`(isPressed: boolean) => void`
Handler that is called when the press state changes.
`onPressEnd`	`(e: ) => void`
Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressStart`	`(e: ) => void`
Handler that is called when a press interaction starts.
`onPress`	`(e: ) => void`
Handler that is called when the press is released over the target.

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

Properties

Name	Type
`y`	`number`
Y position relative to the target.
`x`	`number`
X position relative to the target.
`altKey`	`boolean`
Whether the alt keyboard modifier was held during the press event.
`metaKey`	`boolean`
Whether the meta keyboard modifier was held during the press event.
`ctrlKey`	`boolean`
Whether the ctrl keyboard modifier was held during the press event.
`shiftKey`	`boolean`
Whether the shift keyboard modifier was held during the press event.
`target`	`Element`
The target element of the press event.
`pointerType`
The pointer type that triggered the press event.
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`
The type of press event being fired.

Methods

`continuePropagation(): void`
By default, press events stop propagation to parent elements. In cases where a handler decides not to handle a specific event, it can call `continuePropagation()` to allow a parent to handle it.

Example

This example shows a simple target that handles press events with usePress and logs them to a list below. It also uses the isPressed state to adjust the background color when the target is pressed. Press down on the target and drag your pointer off and over to see when the events are fired, and try focusing the target with a keyboard and pressing the Enter or Space keys to trigger events as well.

Press me!

import React from 'react';
import {usePress} from '@react-aria/interactions';

function Example() {
  let [events, setEvents] = React.useState([]);
  let {pressProps, isPressed} = usePress({
    onPressStart: e => setEvents(
      events => [...events, `press start with ${e.pointerType}`]
    ),
    onPressEnd: e => setEvents(
      events => [...events, `press end with ${e.pointerType}`]
    ),
    onPress: e => setEvents(
      events => [...events, `press with ${e.pointerType}`]
    )
  });

  return (
    <>
      <div
        {...pressProps}
        style={{
          background: isPressed ? 'darkgreen' : 'green',
          color: 'white',
          display: 'inline-block',
          padding: 4,
          cursor: 'pointer'
        }}
        role="button"
        tabIndex={0}>
        Press me!
      </div>
      <ul
        style={{
          maxHeight: '200px',
          overflow: 'auto'
        }}>
        {events.map((e, i) => <li key={i}>{e}</li>)}
      </ul>
    </>
  );
}