From 1155f104284f4dac146e1d5b56a1dd84199a4d5c Mon Sep 17 00:00:00 2001 From: Bartosz Kaszubowski Date: Wed, 18 Nov 2026 10:47:24 +0100 Subject: [PATCH 1/3] docs: add missing docs for `usePressability` hook --- docs/pressable.md | 82 +++++++++++++++++-- .../versioned_docs/version-0.84/pressable.md | 80 ++++++++++++++++-- .../versioned_docs/version-0.85/pressable.md | 80 ++++++++++++++++-- .../versioned_docs/version-0.86/pressable.md | 80 ++++++++++++++++-- .../versioned_docs/version-0.87/pressable.md | 82 +++++++++++++++++-- .../versioned_docs/version-0.88/pressable.md | 82 +++++++++++++++++-- 6 files changed, 441 insertions(+), 45 deletions(-) diff --git a/docs/pressable.md b/docs/pressable.md index e8b8c427be8..0164d078591 100644 --- a/docs/pressable.md +++ b/docs/pressable.md @@ -41,7 +41,11 @@ The touch area never extends past the parent view bounds and the Z-index of sibl :::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 +[implementation](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Pressability/Pressability.js#L350). ::: ## Example @@ -110,6 +114,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 {children}; +} +``` + +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`
Android
@@ -260,10 +292,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. | diff --git a/website/versioned_docs/version-0.84/pressable.md b/website/versioned_docs/version-0.84/pressable.md index 3415bb2eb0a..285d064f317 100644 --- a/website/versioned_docs/version-0.84/pressable.md +++ b/website/versioned_docs/version-0.84/pressable.md @@ -41,7 +41,11 @@ The touch area never extends past the parent view bounds and the Z-index of sibl :::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/facebook/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 +[implementation](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Pressability/Pressability.js#L350). ::: ## Example @@ -110,6 +114,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 {children}; +} +``` + +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`
Android
@@ -260,9 +292,43 @@ Ripple effect configuration for the `android_ripple` property. **Properties:** -| Name | Type | Required | Description | -| ---------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| color | [color](colors) | 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. | +| Name | Type | Description | +| ---------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| color | [color](colors) | 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. | + +### 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. | diff --git a/website/versioned_docs/version-0.85/pressable.md b/website/versioned_docs/version-0.85/pressable.md index 3415bb2eb0a..285d064f317 100644 --- a/website/versioned_docs/version-0.85/pressable.md +++ b/website/versioned_docs/version-0.85/pressable.md @@ -41,7 +41,11 @@ The touch area never extends past the parent view bounds and the Z-index of sibl :::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/facebook/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 +[implementation](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Pressability/Pressability.js#L350). ::: ## Example @@ -110,6 +114,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 {children}; +} +``` + +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`
Android
@@ -260,9 +292,43 @@ Ripple effect configuration for the `android_ripple` property. **Properties:** -| Name | Type | Required | Description | -| ---------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| color | [color](colors) | 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. | +| Name | Type | Description | +| ---------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| color | [color](colors) | 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. | + +### 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. | diff --git a/website/versioned_docs/version-0.86/pressable.md b/website/versioned_docs/version-0.86/pressable.md index 3415bb2eb0a..285d064f317 100644 --- a/website/versioned_docs/version-0.86/pressable.md +++ b/website/versioned_docs/version-0.86/pressable.md @@ -41,7 +41,11 @@ The touch area never extends past the parent view bounds and the Z-index of sibl :::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/facebook/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 +[implementation](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Pressability/Pressability.js#L350). ::: ## Example @@ -110,6 +114,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 {children}; +} +``` + +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`
Android
@@ -260,9 +292,43 @@ Ripple effect configuration for the `android_ripple` property. **Properties:** -| Name | Type | Required | Description | -| ---------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| color | [color](colors) | 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. | +| Name | Type | Description | +| ---------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| color | [color](colors) | 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. | + +### 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. | diff --git a/website/versioned_docs/version-0.87/pressable.md b/website/versioned_docs/version-0.87/pressable.md index e8b8c427be8..0164d078591 100644 --- a/website/versioned_docs/version-0.87/pressable.md +++ b/website/versioned_docs/version-0.87/pressable.md @@ -41,7 +41,11 @@ The touch area never extends past the parent view bounds and the Z-index of sibl :::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 +[implementation](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Pressability/Pressability.js#L350). ::: ## Example @@ -110,6 +114,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 {children}; +} +``` + +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`
Android
@@ -260,10 +292,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. | diff --git a/website/versioned_docs/version-0.88/pressable.md b/website/versioned_docs/version-0.88/pressable.md index e8b8c427be8..0164d078591 100644 --- a/website/versioned_docs/version-0.88/pressable.md +++ b/website/versioned_docs/version-0.88/pressable.md @@ -41,7 +41,11 @@ The touch area never extends past the parent view bounds and the Z-index of sibl :::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 +[implementation](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Pressability/Pressability.js#L350). ::: ## Example @@ -110,6 +114,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 {children}; +} +``` + +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`
Android
@@ -260,10 +292,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. | From 54f771ce3972fac5c3e3e0314c5d3326fd987d46 Mon Sep 17 00:00:00 2001 From: Bartosz Kaszubowski Date: Wed, 18 Nov 2026 10:51:45 +0100 Subject: [PATCH 2/3] simplify example --- docs/pressable.md | 2 +- website/versioned_docs/version-0.84/pressable.md | 2 +- website/versioned_docs/version-0.85/pressable.md | 2 +- website/versioned_docs/version-0.86/pressable.md | 2 +- website/versioned_docs/version-0.87/pressable.md | 2 +- website/versioned_docs/version-0.88/pressable.md | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/pressable.md b/docs/pressable.md index 0164d078591..2e304663fc7 100644 --- a/docs/pressable.md +++ b/docs/pressable.md @@ -130,7 +130,7 @@ function CustomPressable({ children, }: PropsWithChildren<{onPress: () => void}>) { const eventHandlers = usePressability({onPress}); - return {children}; + return {children}; } ``` diff --git a/website/versioned_docs/version-0.84/pressable.md b/website/versioned_docs/version-0.84/pressable.md index 285d064f317..6bb77d78bab 100644 --- a/website/versioned_docs/version-0.84/pressable.md +++ b/website/versioned_docs/version-0.84/pressable.md @@ -130,7 +130,7 @@ function CustomPressable({ children, }: PropsWithChildren<{onPress: () => void}>) { const eventHandlers = usePressability({onPress}); - return {children}; + return {children}; } ``` diff --git a/website/versioned_docs/version-0.85/pressable.md b/website/versioned_docs/version-0.85/pressable.md index 285d064f317..6bb77d78bab 100644 --- a/website/versioned_docs/version-0.85/pressable.md +++ b/website/versioned_docs/version-0.85/pressable.md @@ -130,7 +130,7 @@ function CustomPressable({ children, }: PropsWithChildren<{onPress: () => void}>) { const eventHandlers = usePressability({onPress}); - return {children}; + return {children}; } ``` diff --git a/website/versioned_docs/version-0.86/pressable.md b/website/versioned_docs/version-0.86/pressable.md index 285d064f317..6bb77d78bab 100644 --- a/website/versioned_docs/version-0.86/pressable.md +++ b/website/versioned_docs/version-0.86/pressable.md @@ -130,7 +130,7 @@ function CustomPressable({ children, }: PropsWithChildren<{onPress: () => void}>) { const eventHandlers = usePressability({onPress}); - return {children}; + return {children}; } ``` diff --git a/website/versioned_docs/version-0.87/pressable.md b/website/versioned_docs/version-0.87/pressable.md index 0164d078591..2e304663fc7 100644 --- a/website/versioned_docs/version-0.87/pressable.md +++ b/website/versioned_docs/version-0.87/pressable.md @@ -130,7 +130,7 @@ function CustomPressable({ children, }: PropsWithChildren<{onPress: () => void}>) { const eventHandlers = usePressability({onPress}); - return {children}; + return {children}; } ``` diff --git a/website/versioned_docs/version-0.88/pressable.md b/website/versioned_docs/version-0.88/pressable.md index 0164d078591..2e304663fc7 100644 --- a/website/versioned_docs/version-0.88/pressable.md +++ b/website/versioned_docs/version-0.88/pressable.md @@ -130,7 +130,7 @@ function CustomPressable({ children, }: PropsWithChildren<{onPress: () => void}>) { const eventHandlers = usePressability({onPress}); - return {children}; + return {children}; } ``` From 27e3374e732bfd6ebbcd29a3aa3bb7060c9fc7b3 Mon Sep 17 00:00:00 2001 From: Bartosz Kaszubowski Date: Wed, 18 Nov 2026 10:56:37 +0100 Subject: [PATCH 3/3] use RNRepoLink for state machine graph ref, update line --- docs/pressable.md | 4 +++- website/versioned_docs/version-0.84/pressable.md | 4 +++- website/versioned_docs/version-0.85/pressable.md | 4 +++- website/versioned_docs/version-0.86/pressable.md | 4 +++- website/versioned_docs/version-0.87/pressable.md | 4 +++- website/versioned_docs/version-0.88/pressable.md | 4 +++- 6 files changed, 18 insertions(+), 6 deletions(-) diff --git a/docs/pressable.md b/docs/pressable.md index 2e304663fc7..b9bb53b65ce 100644 --- a/docs/pressable.md +++ b/docs/pressable.md @@ -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 @@ -45,7 +47,7 @@ The touch area never extends past the parent view bounds and the Z-index of sibl existing component without adding a `Pressable` wrapper, see [`usePressability`](#usepressability). For more information about the Pressability state machine, see its -[implementation](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Pressability/Pressability.js#L350). +implementation. ::: ## Example diff --git a/website/versioned_docs/version-0.84/pressable.md b/website/versioned_docs/version-0.84/pressable.md index 6bb77d78bab..411ab55b8b4 100644 --- a/website/versioned_docs/version-0.84/pressable.md +++ b/website/versioned_docs/version-0.84/pressable.md @@ -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 @@ -45,7 +47,7 @@ The touch area never extends past the parent view bounds and the Z-index of sibl existing component without adding a `Pressable` wrapper, see [`usePressability`](#usepressability). For more information about the Pressability state machine, see its -[implementation](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Pressability/Pressability.js#L350). +implementation. ::: ## Example diff --git a/website/versioned_docs/version-0.85/pressable.md b/website/versioned_docs/version-0.85/pressable.md index 6bb77d78bab..411ab55b8b4 100644 --- a/website/versioned_docs/version-0.85/pressable.md +++ b/website/versioned_docs/version-0.85/pressable.md @@ -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 @@ -45,7 +47,7 @@ The touch area never extends past the parent view bounds and the Z-index of sibl existing component without adding a `Pressable` wrapper, see [`usePressability`](#usepressability). For more information about the Pressability state machine, see its -[implementation](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Pressability/Pressability.js#L350). +implementation. ::: ## Example diff --git a/website/versioned_docs/version-0.86/pressable.md b/website/versioned_docs/version-0.86/pressable.md index 6bb77d78bab..411ab55b8b4 100644 --- a/website/versioned_docs/version-0.86/pressable.md +++ b/website/versioned_docs/version-0.86/pressable.md @@ -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 @@ -45,7 +47,7 @@ The touch area never extends past the parent view bounds and the Z-index of sibl existing component without adding a `Pressable` wrapper, see [`usePressability`](#usepressability). For more information about the Pressability state machine, see its -[implementation](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Pressability/Pressability.js#L350). +implementation. ::: ## Example diff --git a/website/versioned_docs/version-0.87/pressable.md b/website/versioned_docs/version-0.87/pressable.md index 2e304663fc7..b9bb53b65ce 100644 --- a/website/versioned_docs/version-0.87/pressable.md +++ b/website/versioned_docs/version-0.87/pressable.md @@ -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 @@ -45,7 +47,7 @@ The touch area never extends past the parent view bounds and the Z-index of sibl existing component without adding a `Pressable` wrapper, see [`usePressability`](#usepressability). For more information about the Pressability state machine, see its -[implementation](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Pressability/Pressability.js#L350). +implementation. ::: ## Example diff --git a/website/versioned_docs/version-0.88/pressable.md b/website/versioned_docs/version-0.88/pressable.md index 2e304663fc7..b9bb53b65ce 100644 --- a/website/versioned_docs/version-0.88/pressable.md +++ b/website/versioned_docs/version-0.88/pressable.md @@ -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 @@ -45,7 +47,7 @@ The touch area never extends past the parent view bounds and the Z-index of sibl existing component without adding a `Pressable` wrapper, see [`usePressability`](#usepressability). For more information about the Pressability state machine, see its -[implementation](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Pressability/Pressability.js#L350). +implementation. ::: ## Example