Skip to main content
Version: 3.x

Touchable

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 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 or Animated API.

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 section below.

RectButton​

To replace RectButton with Touchable, simply add underlayColor="black" to your Touchable. This will animate the underlay when the button is pressed.

<Touchable
  ...
  underlayColor="black"/>

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.

<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}.

<Touchable
  ...
  activeOpacity={0.2}/>

TouchableHighlight​

To replace TouchableHighlight, add activeUnderlayOpacity={1}.

<Touchable
  ...
  activeUnderlayOpacity={1}/>

TouchableWithoutFeedback​

To replace TouchableWithoutFeedback, use a plain Touchable.

<Touchable ... />

TouchableNativeFeedback​

To replicate TouchableNativeFeedback behavior, use the androidRipple prop. Make sure to set foreground={true}.

<Touchable
  ...
  androidRipple={{
    foreground: true,
  }}/>

Example​

In this example we will demonstrate how to recreate RectButton and BorderlessButton effects using the Touchable component.


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' }]}
      underlayColor="black">
      <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({

Properties​

activeOpacity​

activeOpacity?: number;

Defines the opacity of the whole component when the button is active.

defaultOpacity​

defaultOpacity?: number;

Defines the opacity of the whole component when the button is active. By default set to 1.

activeScale​

activeScale?: number;

Defines the scale of the whole component when the button is active.

defaultScale​

defaultScale?: number;

Defines the scale of the whole component when the button is inactive. By default set to 1.

activeUnderlayOpacity​

activeUnderlayOpacity?: number;

Defines the opacity of the underlay when the button is active. By default set to 0.105.

defaultUnderlayOpacity​

defaultUnderlayOpacity?: number;

Defines the initial opacity of underlay when the button is inactive. By default set to 0.

hoverOpacity​

Web
hoverOpacity?: number;

Defines the opacity of the whole component when the button is hovered. By default falls back to defaultOpacity.

hoverScale​

Web
hoverScale?: number;

Defines the scale of the whole component when the button is hovered. By default falls back to defaultScale.

hoverUnderlayOpacity​

Web
hoverUnderlayOpacity?: number;

Defines the opacity of the underlay when the button is hovered. By default falls back to defaultUnderlayOpacity.

animationDuration​


animationDuration?: AnimationDuration;

Press and hover animation timing, in milliseconds. Defaults to 50ms for the in phase and 100ms for the out phase.

Each animation has two phases — in (running while the pointer engages the component) and out (running after the pointer releases) — across two categories:

  • tap — applies to presses.
  • hover — pointer hover (web only).

longPress is an optional override for the press-out timing once the press has been held past delayLongPress. It only has an out field (the press-in is always the tap in duration). If omitted, the long-press release uses the resolved tap out duration.

Three input shapes are accepted:

  1. A single number applied to every phase of every category:
<Touchable animationDuration={200} />
  1. A baseline in / out with optional per-category overrides — categories that aren't specified inherit the baseline, and within a category any field left out also inherits from the baseline:
<Touchable
  animationDuration={{
    in: 50,
    out: 200,
    hover: { in: 400 },
  }}
/>
  1. Both categories specified explicitly (no baseline) — every field must be supplied:
<Touchable
  animationDuration={{
    tap: { in: 0, out: 200 },
    hover: { in: 300, out: 300 },
  }}
/>

To give a long press its own release timing, add longPress.out. The switch fires when the press is held past delayLongPress:

<Touchable
  delayLongPress={400}
  onLongPress={() => {}}
  animationDuration={{
    in: 50,
    out: 100,
    longPress: { out: 500 },
  }}
/>

underlayColor​

underlayColor?: string;

Background color of the underlay. This only takes effect when activeUnderlayOpacity or defaultUnderlayOpacity is set. By default set to transparent.

exclusive​

exclusive?: boolean;

Defines whether pressing this button prevents other buttons exported by Gesture Handler from being pressed. By default set to true.

touchSoundDisabled​

Android
touchSoundDisabled?: boolean;

If set to true, the system will not play a sound when the button is pressed.

onPressIn​


onPressIn?: (e: GestureEvent<NativeHandlerData>) => void;

Triggered when the button gets pressed (analogous to onPressIn in Pressable from RN core).

onPressOut​


onPressOut?: (e: GestureEvent<NativeHandlerData>) => void;

Triggered when the button gets released or the pointer moves outside of the button area (analogous to onPressOut in Pressable from RN core).

onPress​


onPress?: (e: GestureEvent<NativeHandlerData>) => void;

Triggered when the button gets pressed (analogous to onPress in Pressable from RN core).

onLongPress​

onLongPress?: () => void;

Triggered when the button gets pressed for at least delayLongPress milliseconds.

delayLongPress​

delayLongPress?: number;

Defines the delay, in milliseconds, after which the onLongPress callback gets called. By default set to 600.

androidRipple​

Android

androidRipple?: PressableAndroidRippleConfig;

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.

cancelOnLeave​

Android
iOS
cancelOnLeave?: boolean;

Whether the touch should be canceled when the pointer leaves the component. By default set to true. On web this prop doesn't have any effect and behaves as if true was set.

needsOffscreenAlphaCompositing​

Android
needsOffscreenAlphaCompositing?: boolean;

Whether the view should render with an offscreen alpha-compositing buffer when its opacity is less than 1. Defaults to false.

We are Software Mansion.

Hire us