Skip to content

Commit 2e7c7a5

Browse files
devongovettdevongovett
authored
Add docs for useLongPress (#2591)
1 parent 69cf00a commit 2e7c7a5

File tree

3 files changed

+134
-0
lines changed

3 files changed

+134
-0
lines changed

‎packages/@react-aria/interactions/docs/useHover.mdx

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,8 @@ but `:hover` is problematic on touch devices due to mouse emulation in mobile br
4949
and device, `:hover` may never apply, or may apply continuously until the user touches another element.
5050
`useHover` only applies when the pointer is truly capable of hovering, and emulated mouse events are ignored.
5151

52+
Read our [blog post](/blog/building-a-button-part-2.html) about the complexities of hover event handling to learn more.
53+
5254
## Usage
5355

5456
`useHover` returns props that you should spread onto the target element:

‎packages/@react-aria/interactions/docs/useLongPress.mdx

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
<!-- Copyright 2020 Adobe. All rights reserved.
2+
This file is licensed to you under the Apache License, Version 2.0 (the "License");
3+
you may not use this file except in compliance with the License. You may obtain a copy
4+
of the License at http://www.apache.org/licenses/LICENSE-2.0
5+
Unless required by applicable law or agreed to in writing, software distributed under
6+
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
7+
OF ANY KIND, either express or implied. See the License for the specific language
8+
governing permissions and limitations under the License. -->
9+
10+
import {Layout} from '@react-spectrum/docs';
11+
export default Layout;
12+
13+
import docs from 'docs:@react-aria/interactions';
14+
import typesDocs from 'docs:@react-types/shared/src/events.d.ts';
15+
import {HeaderInfo, FunctionAPI, TypeContext, InterfaceType, TypeLink} from '@react-spectrum/docs';
16+
import packageData from '@react-aria/interactions/package.json';
17+
18+
```jsx import
19+
import {useLongPress, usePress} from '@react-aria/interactions';
20+
```
21+
22+
---
23+
category: Interactions
24+
keywords: [long press interactions, long press events, long press gesture, aria]
25+
---
26+
27+
# useLongPress
28+
29+
<p>{docs.exports.useLongPress.description}</p>
30+
31+
<HeaderInfo
32+
packageData={packageData}
33+
componentNames={['useLongPress']} />
34+
35+
## API
36+
37+
<FunctionAPI function={docs.exports.useLongPress} links={docs.links} />
38+
39+
## Features
40+
41+
`useLongPress` handles long press interactions across both mouse and touch devices. A long press is triggered when a user presses
42+
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
43+
time threshold, the interaction is canceled. Once a long press event is triggered, other pointer interactions that may be active
44+
such as `usePress` and `useMove` will be canceled so that only the long press is activated.
45+
46+
* Handles mouse and touch events
47+
* Uses pointer events where available, with fallbacks to mouse and touch events
48+
* Ignores emulated mouse events in mobile browsers
49+
* Prevents text selection on touch devices while long pressing
50+
* Prevents browser and OS context menus from appearing while long pressing
51+
* Customizable time threshold for long press
52+
* Supports an accessibility description to indicate to assistive technology users that a long press action is available
53+
54+
## Usage
55+
56+
`useLongPress` returns props that you should spread onto the target element:
57+
58+
<TypeContext.Provider value={docs.links}>
59+
<InterfaceType properties={docs.links[docs.exports.useLongPress.return.id].properties} />
60+
</TypeContext.Provider>
61+
62+
`useLongPress` supports the following event handlers and options:
63+
64+
<TypeContext.Provider value={docs.links}>
65+
<InterfaceType properties={docs.links[docs.exports.useLongPress.parameters[0].value.id].properties} />
66+
</TypeContext.Provider>
67+
68+
Each of these handlers is fired with a `LongPressEvent`, which exposes information about the target and the
69+
type of event that triggered the interaction.
70+
71+
<TypeContext.Provider value={typesDocs.links}>
72+
<InterfaceType properties={typesDocs.exports.LongPressEvent.properties} />
73+
</TypeContext.Provider>
74+
75+
## Example
76+
77+
This example shows a button that has both a normal press action using [usePress](usePress.html), as well as a long
78+
press action using `useLongPress`. Pressing the button will set the mode to "Normal speed", and long pressing it will
79+
set the mode to "Hyper speed". All of the emitted events are also logged below. Note that when long pressing the button,
80+
only a long press is emitted, and no normal press is emitted on pointer up.
81+
82+
**Note**: this example does not have a keyboard accessible way to trigger the long press action. Because the method of triggering
83+
this action will differ depending on the component, it is outside the scope of `useLongPress`. Make sure to implement a keyboard
84+
friendly alternative to all long press interactions if you are using this hook directly.
85+
86+
```tsx example
87+
import {mergeProps} from '@react-aria/utils';
88+
89+
function Example() {
90+
let [events, setEvents] = React.useState([]);
91+
let [mode, setMode] = React.useState('Activate');
92+
let {longPressProps} = useLongPress({
93+
accessibilityDescription: 'Long press to activate hyper speed',
94+
onLongPressStart: e => setEvents(
95+
events => [`long press start with ${e.pointerType}`, ...events]
96+
),
97+
onLongPressEnd: e => setEvents(
98+
events => [`long press end with ${e.pointerType}`, ...events]
99+
),
100+
onLongPress: e => {
101+
setMode('Hyper speed');
102+
setEvents(
103+
events => [`long press with ${e.pointerType}`, ...events]
104+
);
105+
}
106+
});
107+
108+
let {pressProps} = usePress({
109+
onPress: e => {
110+
setMode('Normal speed');
111+
setEvents(
112+
events => [`press with ${e.pointerType}`, ...events]
113+
);
114+
}
115+
});
116+
117+
return (
118+
<>
119+
<button {...mergeProps(pressProps, longPressProps)}>{mode}</button>
120+
<ul
121+
style={{
122+
maxHeight: '200px',
123+
overflow: 'auto'
124+
}}>
125+
{events.map((e, i) => <li key={i}>{e}</li>)}
126+
</ul>
127+
</>
128+
);
129+
}
130+
```

‎packages/@react-aria/interactions/docs/usePress.mdx

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,8 @@ the visual appearance of the target. If the pointer is released over the target,
5252
* Handles canceling press interactions on scroll
5353
* Normalizes many cross browser inconsistencies
5454

55+
Read our [blog post](/blog/building-a-button-part-1.html) about the complexities of press event handling to learn more.
56+
5557
## Usage
5658

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

0 commit comments

Comments
 (0)