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.

Press me!

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

function Example() {
  let [events, setEvents] = React.useState<string[]>([]);
  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: '8px 12px',
          borderRadius: 8,
          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>
    </>
  );
}

Features

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
Normalizes focus behavior on mouse and touch interactions across browsers
Disables text selection while the press interaction is active
Cancels press interactions on scroll
Normalizes many cross browser inconsistencies

Read our blog post learn more.

API

usePress(props: PressHookProps): PressResult

PressEvents

Name	Type

PressResult

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

PressEvent

Properties

Name	Type
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`
The type of press event being fired.
`pointerType`	`PointerType`
The pointer type that triggered the press event.
`shiftKey`	`boolean`
Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`
Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`
Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`
Whether the alt keyboard modifier was held during the press event.
`x`	`number`
X position relative to the target.
`y`	`number`
Y position relative to the target.
`key`	`string`
The key that triggered the press event, if it was triggered by a keyboard interaction. This is useful for differentiating between Space and Enter key presses.

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.