@tudp/rn-image-zoom

A gesture-driven React Native image viewer with smooth pinch, double-tap, and pan zooming powered by Reanimated and Gesture Handler.

Features

• Pinch, pan, and double-tap gestures with configurable scale limits
• Momentum-aware panning with natural friction and boundary clamping
• Optional modal experience that lets users swipe between multiple photos
• Loading and error states with customizable colors
• Callbacks for scale changes and zoom lifecycle events

Installation

Install the package in your React Native project:

# using yarn
yarn add @tudp/rn-image-zoom

# or with npm
npm install @tudp/rn-image-zoom

The component relies on community gesture and animation libraries. Make sure the peer dependencies are installed and configured in your app:

yarn add react-native-gesture-handler react-native-reanimated

Follow the official setup guides for Gesture Handler and Reanimated if you have not already done so.

Quick start

Wrap your app with GestureHandlerRootView, supply the image uri, and optionally tune the scale limits or callbacks.

import React from 'react';
import { SafeAreaView, StyleSheet } from 'react-native';
import { GestureHandlerRootView } from 'react-native-gesture-handler';

import { ImageZoom } from '@tudp/rn-image-zoom';

export function PhotoScreen() {
  return (
    <GestureHandlerRootView style={styles.root}>
      <SafeAreaView style={styles.root}>
        <ImageZoom
          uri="https://images.unsplash.com/photo-1469474968028-56623f02e42e"
          minScale={1}
          maxScale={5}
          onScaleChange={(scale) => console.log('scale', scale)}
        />
      </SafeAreaView>
    </GestureHandlerRootView>
  );
}

const styles = StyleSheet.create({
  root: {
    flex: 1,
    backgroundColor: '#050505',
  },
});

Modal viewer preview

The example app ships with an optional modal flow where tapping the inline preview opens a fullscreen carousel. You can recreate it by combining state with the ImageZoom component:

const [showModal, setShowModal] = useState(false);

return (
  <>
    <TouchableOpacity onPress={() => setShowModal(true)}>
      <Image source={{ uri }} style={styles.thumbnail} />
    </TouchableOpacity>

    <Modal visible={showModal} onRequestClose={() => setShowModal(false)}>
      <GestureHandlerRootView style={styles.modalRoot}>
        <ImageZoom
          uri={uri}
          minScale={1}
          maxScale={5}
          backgroundColor="#000"
          onZoomEnd={() => console.log('zoom finished')}
        />
      </GestureHandlerRootView>
    </Modal>
  </>
);

See example/src/App.tsx for a more complete playground, including multi-image swiping when the modal is open.

Props

| Prop | Type | Default | Description | | ---- | ---- | ------- | ----------- | | uri | string | required | Remote image source to display. | | minScale | number | 1 | Minimum zoom level applied when resetting or loading. | | maxScale | number | 5 | Maximum zoom level attainable via pinch or double tap. | | doubleTapToZoom | boolean | true | Enables double-tap gesture that toggles between min and an auto-calculated zoom. | | pinchToZoom | boolean | true | Enables pinch gesture for scaling. | | panEnabled | boolean | true | Enables panning when the image is larger than the viewport. | | style | ViewStyle | – | Style overrides for the root container. | | imageStyle | ImageStyle | – | Style overrides for the underlying Animated.Image. | | backgroundColor | string | '#121212' | Background color behind the image (and used when loading). | | loadingColor | string | – | Spinner color displayed while the image is loading. | | errorColor | string | – | Text color for the fallback error message. | | showLoading | boolean | true | Toggle the loading indicator visibility. | | onScaleChange | (scale: number) => void | – | Fired with the current scale factor on updates. | | onZoomBegin | () => void | – | Called when a pinch or double-tap zoom begins. | | onZoomEnd | () => void | – | Called after the zoom animation settles. | | onLoad | () => void | – | Triggered once the image dimensions have been resolved. | | onError | (error: any) => void | – | Triggered if loading the image fails. | | animationDuration | number | 200 | Duration (ms) for timing animations used during resets. | | testID | string | – | Identifier forwarded to the root container for testing. |

Example app

This repository includes an Expo-style playground under example/ that demonstrates inline and modal usage.

yarn install
yarn example ios   # or: yarn example android

Development

Run linting and tests from the repo root:

yarn lint
yarn test

Build artifacts are generated with Bob via:

yarn clean
yarn prepare

License

MIT © tudp