[Docs] Touchable

packages/docs-gesture-handler/docs/components/buttons.mdx

@@ -9,6 +9,10 @@ import GifGallery from '@site/components/GifGallery';
 
 import HeaderWithBadges from '@site/src/components/HeaderWithBadges';
 
+:::danger
+Button components described in this section are deprecated and will be removed in the future. Please use [`Touchable`](/docs/components/touchable) instead.
+:::
+
 <GifGallery>
   <img src={useBaseUrl('gifs/samplebutton.gif')} width="280" />
 </GifGallery>
@@ -37,7 +41,7 @@ The most basic button component does not provide any feedback and lacks props su
 exclusive?: boolean;
 ```
 
-Defines if more than one button could be pressed simultaneously. By default set to `true`.
+Defines whether pressing this button prevents other buttons exported by Gesture Handler from being pressed. By default set to `true`.
 
 <HeaderWithBadges platforms={['android']}>
 ### rippleColor
@@ -194,7 +198,7 @@ If you wish to get specific information about platforms design patterns, visit [
 
 This library allows the use of native components with native feedback in adequate situations.
 
-If you do not wish to implement a custom design approach, [`RectButton`](#rectbutton) and [`BorderlessButton`](#borderlessbutton) seem to be absolutely enough and there's no need to use anything else. In all the remaining cases, you can always rely on [`BaseButton`](#basebutton) which is a superclass for the other button classes and can be used as a generic `Touchable` replacement that can be customized to your needs.
+If you do not wish to implement a custom design approach, [`RectButton`](#rectbutton) and [`BorderlessButton`](#borderlessbutton) seem to be absolutely enough and there's no need to use anything else. In all the remaining cases, you can always rely on [`BaseButton`](#basebutton) which is a superclass for the other button classes and can be used as a generic React Native `Touchable` replacement that can be customized to your needs.
 
 Below we list some of the common usecases for button components to be used along with the type of button that should be used according to the platform specific design guidelines.
 

packages/docs-gesture-handler/docs/components/touchable.mdx

@@ -0,0 +1,326 @@
+---
+id: touchable
+title: Touchable
+sidebar_label: Touchable
+---
+
+import HeaderWithBadges from '@site/src/components/HeaderWithBadges';
+
+:::note
+This section refers to new `Touchable` component, meant to replace both buttons and touchables. If you are looking for documentation for the deprecated touchable components, check out the [Legacy Touchables](/docs/components/legacy-touchables) section.
+:::
+
+`Touchable` is a versatile new component introduced in Gesture Handler 3 to supersede previous button implementations. Designed for maximum flexibility, it provides a highly customizable interface for native touch handling while ensuring consistent behavior across platforms.
+
+`Touchable` provides a simple interface for the common animations like opacity, underlay, and scale, implemented entirely on the platform. On Android, it also exposes the native ripple effect on press (turned off by default).
+
+If the provided animations are not sufficient, it's possible to use `Touchable` to create fully custom interactions using either [Reanimated](https://docs.swmansion.com/react-native-reanimated/) or [Animated API](https://reactnative.dev/docs/animated).
+
+## Replacing old buttons
+
+If you were using `RectButton` or `BorderlessButton` in your app, you should replace them with `Touchable`. Check out the full code in the [example](#example) section below.
+
+### RectButton
+
+To replace `RectButton` with `Touchable`, simply add `activeUnderlayOpacity={0.105}` to your `Touchable`. This will animate the underlay when the button is pressed.
+
+```tsx
+<Touchable
+  ...
+  activeUnderlayOpacity={0.105}/>
+```
+
+### BorderlessButton
+
+Replacing `BorderlessButton` with `Touchable` is as easy as replacing `RectButton`. Just add `activeOpacity={0.3}` to your `Touchable`. This will animate the whole component when the button is pressed.
+
+```tsx
+<Touchable
+  ...
+  activeOpacity={0.3}/>
+```
+
+## Migrating from legacy Touchable variants
+
+If you were using the specialized touchable components (`TouchableOpacity`, `TouchableHighlight`, `TouchableWithoutFeedback`, or `TouchableNativeFeedback`), you can replicate their behavior with the unified `Touchable` component.
+
+### TouchableOpacity
+
+To replace `TouchableOpacity`, add `activeOpacity={0.2}`.
+
+```tsx
+<Touchable
+  ...
+  activeOpacity={0.2}/>
+```
+
+### TouchableHighlight
+
+To replace `TouchableHighlight`, add `activeUnderlayOpacity={1}`.
+
+```tsx
+<Touchable
+  ...
+  activeUnderlayOpacity={1}/>
+```
+
+### TouchableWithoutFeedback
+
+To replace `TouchableWithoutFeedback`, use a plain `Touchable`.
+
+```tsx
+<Touchable ... />
+```
+
+### TouchableNativeFeedback
+
+To replicate `TouchableNativeFeedback` behavior, use the [`androidRipple`](#androidripple) prop. Make sure to set `foreground={true}`.
+
+```tsx
+<Touchable
+  ...
+  androidRipple={{
+    foreground: true,
+  }}/>
+```
+
+## Example 
+
+In this example we will demonstrate how to recreate `RectButton` and `BorderlessButton` effects using the `Touchable` component.
+
+<CollapsibleCode 
+label="Show full example"
+expandedLabel="Hide full example"
+lineBounds={[7, 40]}
+src={`
+import React from 'react';
+import { StyleSheet, Text } from 'react-native';
+import {
+  GestureHandlerRootView,
+  Touchable,
+} from 'react-native-gesture-handler';
+
+export default function TouchableExample() {
+  return (
+    <GestureHandlerRootView style={styles.container}>
+      <Touchable
+        onPress={() => {
+          console.log('BaseButton built with Touchable');
+        }}
+        style={[styles.button, { backgroundColor: '#7d63d9' }]}>
+        <Text style={styles.buttonText}>BaseButton</Text>
+      </Touchable>
+
+      <Touchable
+        onPress={() => {
+          console.log('RectButton built with Touchable');
+        }}
+        style={[styles.button, { backgroundColor: '#4f9a84' }]}
+        activeUnderlayOpacity={0.105}>
+        <Text style={styles.buttonText}>RectButton</Text>
+      </Touchable>
+
+      <Touchable
+        onPress={() => {
+          console.log('BorderlessButton built with Touchable');
+        }}
+        style={[styles.button, { backgroundColor: '#5f97c8' }]}
+        activeOpacity={0.3}>
+        <Text style={styles.buttonText}>BorderlessButton</Text>
+      </Touchable>
+    </GestureHandlerRootView>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+
+    gap: 20,
+  },
+  button: {
+    width: 200,
+    height: 70,
+    borderRadius: 15,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  buttonText: {
+    color: 'white',
+    fontSize: 14,
+    fontWeight: '600',
+  },
+});
+`}/>
+
+
+## Properties
+
+### activeOpacity
+
+```ts
+activeOpacity?: number;
+```
+
+Defines the opacity of the whole component when the button is active.
+
+### defaultOpacity
+
+```ts
+defaultOpacity?: number;
+```
+
+Defines the opacity of the whole component when the button is active. By default set to `1`.
+
+### activeUnderlayOpacity
+
+```ts
+activeUnderlayOpacity?: number;
+```
+
+Defines the opacity of the underlay when the button is active. By default set to `0`.
+
+### defaultUnderlayOpacity
+
+```ts
+defaultUnderlayOpacity?: number;
+```
+
+Defines the initial opacity of underlay when the button is inactive. By default set to `0`.
+
+### underlayColor
+
+```ts
+underlayColor?: string;
+```
+
+Background color of the underlay. This only takes effect when `activeUnderlayOpacity` or `defaultUnderlayOpacity` is set.
+
+### exclusive
+
+```ts
+exclusive?: boolean;
+```
+
+Defines whether pressing this button prevents other buttons exported by Gesture Handler from being pressed. By default set to `true`.
+
+<HeaderWithBadges platforms={['android']}>
+### touchSoundDisabled
+</HeaderWithBadges>
+
+```ts
+touchSoundDisabled?: boolean;
+```
+
+If set to `true`, the system will not play a sound when the button is pressed.
+
+### onPressIn
+
+<CollapsibleCode 
+label="Show composed types definitions"
+expandedLabel="Hide composed types definitions"
+lineBounds={[0, 1]}
+src={`
+onPressIn?: (e: GestureEvent<NativeHandlerData>) => void;
+
+type GestureEvent<NativeHandlerData> = {
+    handlerTag: number;
+    numberOfPointers: number;
+    pointerType: PointerType;
+    pointerInside: boolean;
+}
+
+enum PointerType {
+    TOUCH,
+    STYLUS,
+    MOUSE,
+    KEY,
+    OTHER,
+}
+`}/>
+
+Triggered when the button gets pressed (analogous to `onPressIn` in `Pressable` from RN core).
+
+### onPressOut
+
+<CollapsibleCode 
+label="Show composed types definitions"
+expandedLabel="Hide composed types definitions"
+lineBounds={[0, 1]}
+src={`
+onPressOut?: (e: GestureEvent<NativeHandlerData>) => void;
+
+type GestureEvent<NativeHandlerData> = {
+    handlerTag: number;
+    numberOfPointers: number;
+    pointerType: PointerType;
+    pointerInside: boolean;
+}
+
+enum PointerType {
+    TOUCH,
+    STYLUS,
+    MOUSE,
+    KEY,
+    OTHER,
+}
+`}/>
+
+Triggered when the button gets released or the pointer moves outside of the button area (analogous to `onPressOut` in `Pressable` from RN core).
+
+### onPress
+
+```ts
+onPress?: (pointerInside: boolean) => void;
+```
+
+Triggered when the button gets pressed (analogous to `onPress` in `Pressable` from RN core).
+
+### onLongPress
+
+```ts
+onLongPress?: () => void;
+```
+
+Triggered when the button gets pressed for at least [`delayLongPress`](#delaylongpress) milliseconds.
+
+
+### onActiveStateChange
+
+```ts
+onActiveStateChange?: (active: boolean) => void;
+```
+
+Triggered when the button transitions between active and inactive states. It passes the current active state as a boolean variable to the method as the first parameter.
+
+### delayLongPress
+
+```ts
+delayLongPress?: number;
+```
+
+Defines the delay, in milliseconds, after which the [`onLongPress`](#onlongpress) callback gets called. By default set to `600`.
+
+
+<HeaderWithBadges platforms={['android']}>
+### androidRipple
+</HeaderWithBadges>
+
+<CollapsibleCode 
+label="Show composed types definitions"
+expandedLabel="Hide composed types definitions"
+lineBounds={[0, 1]}
+src={`
+androidRipple?: PressableAndroidRippleConfig;
+
+type PressableAndroidRippleConfig = {
+    color?: (string | OpaqueColorValue);
+    borderless?: boolean;
+    radius?: number;
+    foreground?: boolean;
+}
+`}/>
+
+Configuration for the ripple effect on Android. If not provided, the ripple effect will be disabled. If `{}` is provided, the ripple effect will be enabled with default configuration.

packages/docs-gesture-handler/docs/components/touchables.md

@@ -1,11 +1,11 @@
 ---
-id: touchables
-title: Touchables
-sidebar_label: Touchables
+id: legacy-touchables
+title: Legacy Touchables
+sidebar_label: Legacy Touchables
 ---
 
 :::warning
-Touchables will be removed in the future version of Gesture Handler. Use [`Pressable`](/docs/components/pressable) instead.
+Touchables will be removed in the future version of Gesture Handler. Use [`Touchable`](/docs/components/touchable) instead.
 :::
 
 Gesture Handler library provides an implementation of RN's touchable components that are based on [native buttons](buttons.mdx) and do not rely on the JS responder system utilized by RN. Our touchable implementation follows the same API and aims to be a drop-in replacement for touchables available in React Native.

packages/docs-gesture-handler/docs/guides/troubleshooting.mdx

@@ -32,7 +32,7 @@ This library is maintained by a very small team. Please keep this in mind when r
 
 - Changing `enabled` prop during a gesture has no effect, only when a gesture starts (that is, a finger touches the screen) the `enabled` prop is taken into consideration to decide whether to extract (or not) the gesture and provide it with stream of events to analyze.
 - `Native` gesture may not conform to the standard state flow due to platform specific workarounds to incorporate native views into RNGH.
-- Keep in mind that [`Touchables`](/docs/components/touchables) from RNGH are rendering two additional views that may need to be styled separately to achieve desired effect (`style` and `containerStyle` props).
+- Keep in mind that [Legacy `Touchables`](/docs/components/legacy-touchables) from RNGH are rendering two additional views that may need to be styled separately to achieve desired effect (`style` and `containerStyle` props).
 - In order for the [gesture composition](/docs/fundamentals/gesture-composition) to work, all composed gestures must be attached to the same [`GestureHandlerRootView`](/docs/fundamentals/root-view).
 
 ## Multiple instances of Gesture Handler were detected

packages/docs-gesture-handler/docs/guides/upgrading-to-3.mdx

@@ -246,7 +246,17 @@ code2={
 
 ### Buttons
 
-The implementation of buttons has been updated, resolving most button-related issues. They have also been internally rewritten to utilize the new hook API. The original button components are still accessible but have been renamed with the prefix `Legacy`, e.g., `RectButton` is now available as `LegacyRectButton`.
+RNGH3 introduces the [`Touchable`](/docs/components/touchable) component — a flexible, unified replacement for all previous button types. While `Touchable` shares the same logic as our standard buttons, it offers a more customizable API.
+
+To help you migrate, here is the current state of our button components:
+
+- [`Touchable`](/docs/components/touchable) - The recommended component. Can be used to replicate both `RectButton` and `BorderlessButton` effects by adjusting the `activeOpacity` and `activeUnderlayOpacity` props.
+  - To replace `RectButton`, add `activeUnderlayOpacity={0.105}`.
+  - To replace `BorderlessButton`, add `activeOpacity={0.3}`.
+
+- Standard Buttons (Deprecated) - `BaseButton`, `RectButton` and `BorderlessButton` are still available but are now deprecated. They have been internally rewritten using the new Hooks API to resolve long-standing issues.
+
+- Legacy Buttons (Deprecated): The original, pre-rewrite versions are still accessible, but have been renamed with a `Legacy` prefix (e.g., `LegacyRectButton`).
 
 Although the legacy JS implementation of the buttons is still available, they also use the new host component internally. Because of that, `PureNativeButton` is no longer available in Gesture Handler 3.