Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 76 additions & 8 deletions docs/pressable.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ id: pressable
title: Pressable
---

import RNRepoLink from '@site/core/RNRepoLink';

Pressable is a Core Component wrapper that can detect various stages of press interactions on any of its defined children.

```tsx
Expand Down Expand Up @@ -41,7 +43,11 @@ The touch area never extends past the parent view bounds and the Z-index of sibl
</figure>

:::info
`Pressable` uses React Native's `Pressability` API. For more information around the state machine flow of Pressability and how it works, check out the implementation for [Pressability](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Pressability/Pressability.js#L350).
`Pressable` uses React Native's `Pressability` API. To apply press handling to an
existing component without adding a `Pressable` wrapper, see
[`usePressability`](#usepressability). For more information about the
Pressability state machine, see its
<RNRepoLink href="/packages/react-native/Libraries/Pressability/Pressability.js#L342">implementation</RNRepoLink>.
:::

## Example
Expand Down Expand Up @@ -110,6 +116,34 @@ const styles = StyleSheet.create({
export default App;
```

## Hooks

### `usePressability`

Use `usePressability` to add press handling directly to an existing host component, such as a `View`, without adding a `Pressable` wrapper.
For most use cases `Pressable` is sufficient, but sometime using pressability event handlers directly it may be helpful.

```tsx
import type {PropsWithChildren} from 'react';
import {usePressability, View} from 'react-native';

function CustomPressable({
onPress,
children,
}: PropsWithChildren<{onPress: () => void}>) {
const eventHandlers = usePressability({onPress});
return <View {...eventHandlers}>{children}</View>;
}
```

The hook accepts a [`PressabilityConfig`](pressable#pressabilityconfig) and returns `PressabilityEventHandlers` to spread onto the host component. Both types are exported from `react-native`.

```tsx
usePressability(config?: PressabilityConfig | null): PressabilityEventHandlers | null;
```

Pass `null` or `undefined` to defer initialization. The hook returns `null` until initialized. After initialization, it remains active until the component unmounts.

## Props

### `android_disableSound` <div className="label android">Android</div>
Expand Down Expand Up @@ -260,10 +294,44 @@ Ripple effect configuration for the `android_ripple` property.

**Properties:**

| Name | Type | Required | Description |
| ---------- | ------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| color | [color](colors) or [PlatformColor](platformcolor) | No | Defines the color of the ripple effect. |
| borderless | boolean | No | Defines if ripple effect should not include border. |
| radius | number | No | Defines the radius of the ripple effect. |
| foreground | boolean | No | Set to true to add the ripple effect to the foreground of the view, instead of the background. This is useful if one of your child views has a background of its own, or you're e.g. displaying images, and you don't want the ripple to be covered by them. |
| alpha | number | No | Controls the opacity of the ripple. Accepts a value between `0.0` (fully transparent) and `1.0` (fully opaque). The value is applied on top of any alpha already present in the color. |
| Name | Type | Description |
| ---------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| color | [color](colors) or [PlatformColor](platformcolor) | Defines the color of the ripple effect. |
| borderless | boolean | Defines if ripple effect should not include border. |
| radius | number | Defines the radius of the ripple effect. |
| foreground | boolean | Set to true to add the ripple effect to the foreground of the view, instead of the background. This is useful if one of your child views has a background of its own, or you're e.g. displaying images, and you don't want the ripple to be covered by them. |
| alpha | number | Controls the opacity of the ripple. Accepts a value between `0.0` (fully transparent) and `1.0` (fully opaque). The value is applied on top of any alpha already present in the color. |

### PressabilityConfig

Configuration for the [`usePressability`](#usepressability) hook.

| Type |
| ------ |
| object |

**Properties:**

| Name | Type | Description |
| -------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------- |
| android_disableSound | boolean | Disables the Android system sound when `onPress` fires. |
| blockNativeResponder | boolean | Prevents other components from becoming the responder while the press is active. |
| cancelable | boolean | Whether a parent gesture, such as a scroll event, can interrupt the press. |
| delayHoverIn | number | Duration to wait after hover in before calling `onHoverIn`. |
| delayHoverOut | number | Duration to wait after hover out before calling `onHoverOut`. |
| delayLongPress | number | Duration after `delayPressIn` before a press is considered a long press. |
| delayPressIn | number | Duration to wait after press down before calling `onPressIn`. |
| delayPressOut | number | Duration to wait after releasing before calling `onPressOut`. |
| disabled | boolean | Whether to disable initialization of the press gesture. |
| hitSlop | [Rect](rect) or number | Additional distance outside the element where a press can start. |
| minPressDuration | number | Minimum duration between calling `onPressIn` and `onPressOut`. |
| onBlur | `md (event: BlurEvent) => unknown` | Called after the element loses focus. |
| onFocus | `md (event: FocusEvent) => unknown` | Called after the element receives focus. |
| onHoverIn | `md (event: MouseEvent) => unknown` | Called when the hover is activated to provide visual feedback. |
| onHoverOut | `md (event: MouseEvent) => unknown` | Called when the hover is deactivated to undo visual feedback. |
| onLongPress | `md (event: GestureResponderEvent) => unknown` | Called when a long press gesture has been triggered. |
| onPress | `md (event: GestureResponderEvent) => unknown` | Called when a press gesture has been triggered. |
| onPressIn | `md (event: GestureResponderEvent) => unknown` | Called when the press is activated to provide visual feedback. |
| onPressMove | `md (event: GestureResponderEvent) => unknown` | Called when the press location moves. |
| onPressOut | `md (event: GestureResponderEvent) => unknown` | Called when the press is deactivated to undo visual feedback. |
| pressRectOffset | [Rect](rect) or number | Additional distance outside the hit area where a press remains active. |
Loading
Loading