React Native Gesture Image Viewer

English | 한국어

Overview

Have you ever struggled with implementing complex gesture handling and animations when building image galleries or content viewers in React Native?

Existing libraries often have limited customization options or performance issues. react-native-gesture-image-viewer is a high-performance universal gesture viewer library built on React Native Reanimated and Gesture Handler, providing complete customization and intuitive gesture support for not only images but also videos, custom components, and any other content.

Key Features

• ✅ Complete Gesture Support - Pinch zoom, double-tap zoom, swipe navigation, vertical drag dismiss
• ✅ High-Performance Animations - Smooth 60fps animations powered by React Native Reanimated
• ✅ Full Customization - Complete control over components, styles, and behaviors
• ✅ External Control API - Programmatic control from buttons or other components
• ✅ Multi-Instance Management - ID-based independent management of multiple viewers
• ✅ Flexible Integration - Use with Modal, React Native Modal, ScrollView, FlatList, FlashList, Expo Image, FastImage, and more
• ✅ Full TypeScript Support - Enhanced developer experience with smart type inference
• ✅ Cross-Platform - iOS, Android, and Web support
• ✅ Easy-to-Use API - Intuitive and simple implementation without complex setup
• ✅ Various Environment Support - Expo Go and New Architecture support

Quick Start

Examples & Demo

• 📁 Example Project - Real implementation code with various use cases
• 🤖 Expo Go - Try it instantly on Snack Expo

Prerequisites

[!IMPORTANT] react-native-gesture-image-viewer is a high-performance viewer library built on react-native-reanimated and react-native-gesture-handler.
Therefore, you must install React Native Reanimated and Gesture Handler before using this library. Please refer to the official documentation of these libraries for detailed setup guides.

1npm install react-native-reanimated
2npm install react-native-gesture-handler

Minimum Requirements

Library	Minimum Version
react	>=18.0.0
react-native	>=0.75.0
react-native-gesture-handler	>=2.24.0
react-native-reanimated	>=3.0.0

React Native Reanimated Setup

Add the plugin to your babel.config.js:

1// babel.config.js
2module.exports = {
3  presets: [
4    ... // don't add it here :)
5  ],
6  plugins: [
7    ...
8    // for web
9    '@babel/plugin-proposal-export-namespace-from',
10    // react-native-reanimated/plugin has to be listed last.
11    'react-native-reanimated/plugin',
12  ],
13};

Wrap your Metro config with wrapWithReanimatedMetroConfig in metro.config.js:

1const {
2  wrapWithReanimatedMetroConfig,
3} = require('react-native-reanimated/metro-config');
4
5const config = {
6  // Your existing Metro configuration options
7};
8
9module.exports = wrapWithReanimatedMetroConfig(config);

react-native-gesture-handler Setup

• react-native-gesture-handler generally doesn't require additional setup, but please refer to the official documentation for your specific environment.
• For using gestures in Android modals, you would normally need to wrap modal content with GestureHandlerRootView. However, this library already includes GestureHandlerRootView internally, so no additional wrapping is needed when using modals.

Installation

1# npm
2npm install react-native-gesture-image-viewer
3
4# pnpm
5pnpm add react-native-gesture-image-viewer
6
7# yarn
8yarn add react-native-gesture-image-viewer
9
10# bun
11bun add react-native-gesture-image-viewer

Usage

Basic Usage

react-native-gesture-image-viewer is a library focused purely on gesture interactions for complete customization.
You can create a viewer using any Modal of your choice as shown below:

1import { Image, Modal } from 'react-native';
2import { GestureViewer } from 'react-native-gesture-image-viewer';
3
4function App() {
5  const images = [...];
6  const [visible, setVisible] = useState(false);
7
8  // Wrap with useCallback for performance optimization
9  const renderImage = useCallback((imageUrl: string) => {
10    return <Image source={{ uri: imageUrl }} style={{ width: '100%', height: '100%' }} resizeMode="contain" />;
11  }, []);
12
13  return (
14    <Modal visible={visible} onRequestClose={() => setVisible(false)}>
15      <GestureViewer
16        data={images}
17        renderItem={renderImage}
18        onDismiss={() => setVisible(false)}
19      />
20    </Modal>
21  );
22}

Gesture Features

react-native-gesture-image-viewer supports various gestures essential for viewers. All gestures are enabled by default.

1function App() {
2  return (
3    <GestureViewer
4      data={images}
5      renderItem={renderImage}
6      enableDismissGesture
7      enableSwipeGesture
8      enableZoomGesture
9      enableDoubleTapGesture
10      enableZoomPanGesture
11    />
12  )
13}

Property	Description	Default
enableDismissGesture	Calls onDismiss function when swiping down. Useful for closing modals with downward swipe gestures.	true
enableSwipeGesture	Controls left/right swipe gestures. When false, horizontal gestures are disabled.	true
enableZoomGesture	Controls two-finger pinch gestures with focal point zooming. When false, pinch zoom is disabled. Zoom centers on the point between your two fingers for intuitive scaling.	true
enableDoubleTapGesture	Controls double-tap zoom gestures with precision targeting. When false, double-tap zoom is disabled. Zoom centers exactly on the tapped location.	true
enableZoomPanGesture	Enables panning when zoomed in with automatic boundary detection. When false, movement is disabled during zoom. Prevents content from moving outside visible screen area.	true

Custom Components

react-native-gesture-image-viewer offers powerful complete component customization. You can create gesture-supported items with not only images but any component you want.

List Components

Support for any list component like ScrollView, FlatList, FlashList through the ListComponent prop.
The listProps provides type inference based on the selected list component, ensuring accurate autocompletion and type safety in your IDE.

1import { FlashList } from '@shopify/flash-list';
2
3function App() {
4  return (
5    <GestureViewer
6      data={images}
7      ListComponent={FlashList}
8      listProps={{
9        // ✅ FlashList props autocompletion
10      }}
11    />
12  );
13}

Content Components

You can inject various types of content components like expo-image, FastImage, etc., through the renderItem prop to use gestures.

1import { GestureViewer } from 'react-native-gesture-image-viewer';
2import { Image } from 'expo-image';
3
4function App() {
5  const renderImage = useCallback((imageUrl: string) => {
6    return <Image source={{ uri: imageUrl }} style={{ width: '100%', height: '100%' }} contentFit="contain" />;
7  }, []);
8
9  return (
10    <GestureViewer
11      data={images}
12      renderItem={renderImage}
13    />
14  );
15}

External Control API

react-native-gesture-image-viewer provides powerful hooks for programmatic control from buttons or other components.

1import { GestureViewer, useGestureViewerController } from 'react-native-gesture-image-viewer';
2
3function App() {
4  const { goToIndex, goToPrevious, goToNext, currentIndex, totalCount } = useGestureViewerController();
5
6  return (
7    <View>
8      <GestureViewer
9        data={images}
10        renderItem={renderImage}
11      />
12      <View
13        style={{
14          position: 'absolute',
15          bottom: 40,
16          left: 0,
17          right: 0,
18          gap: 10,
19          flexDirection: 'column',
20        }}
21      >
22        <Feather.Button name="chevron-left" onPress={goToPrevious} />
23        <Button title="Jump to index 2" onPress={() => goToIndex(2)} />
24        <Feather.Button name="chevron-right" onPress={goToNext} />
25        <Text>{`${currentIndex + 1} / ${totalCount}`}</Text>
26      </View>
27    </View>
28  );
29}

Style Customization

You can customize the styling of GestureViewer.

1import { GestureViewer } from 'react-native-gesture-image-viewer';
2
3function App() {
4  return (
5    <GestureViewer
6      animateBackdrop={false}
7      width={400}
8      containerStyle={{ /* ... */ }}
9      backdropStyle={{ backgroundColor: 'rgba(0, 0, 0, 0.90)' }}
10      renderContainer={(children) => <View style={{ flex: 1 }}>{children}</View>}
11    />
12  );
13}

Property	Description	Default
animateBackdrop	By default, the background opacity gradually decreases from 1 to 0 during downward swipe gestures. When false, this animation is disabled.	true
width	The width of content items. Default is window width.	Dimensions width
containerStyle	Allows custom styling of the container that wraps the list component.	flex: 1
backdropStyle	Allows customization of the viewer's background style.	backgroundColor: black; StyleSheet.absoluteFill;
renderContainer	Allows custom wrapper component around <GestureViewer />.

Multi-Instance Management

When you want to efficiently manage multiple GestureViewer instances, you can use the id prop to use multiple GestureViewer components.
GestureViewer automatically removes instances from memory when components are unmounted, so no manual memory management is required.

The default id value is default.

1import { GestureViewer, useGestureViewerController } from 'react-native-gesture-image-viewer';
2
3const firstViewerId = 'firstViewerId';
4const secondViewerId = 'secondViewerId';
5
6function App() {
7  const { currentIndex: firstCurrentIndex, totalCount: firstTotalCount } = useGestureViewerController(firstViewerId);
8  const { currentIndex: secondCurrentIndex, totalCount: secondTotalCount } = useGestureViewerController(secondViewerId);
9
10  return (
11    <View>
12      <GestureViewer
13        id={firstViewerId}
14        data={images}
15        renderItem={renderImage}
16      />
17      <GestureViewer
18        id={secondViewerId}
19        data={images}
20        renderItem={renderImage}
21      />
22    </View>
23  );
24}

Additional Props

onIndexChange

The onIndexChange callback function is called when the index value changes.

1import { GestureViewer } from 'react-native-gesture-image-viewer';
2
3function App() {
4  const [currentIndex, setCurrentIndex] = useState(0);
5
6  return (
7    <GestureViewer
8      onIndexChange={setCurrentIndex}
9    />
10  );
11}

useSnap

Sets the scroll behavior mode. false (default) uses paging mode, true uses snap mode.

1import { GestureViewer } from 'react-native-gesture-image-viewer';
2
3function App() {
4  return (
5    <GestureViewer
6      data={data}
7      renderItem={renderItem}
8      useSnap={true}
9    />
10  );
11}

itemSpacing

Sets the spacing between items in pixels. Only applied when useSnap is true.

1import { GestureViewer } from 'react-native-gesture-image-viewer';
2
3function App() {
4  return (
5    <GestureViewer
6      data={data}
7      renderItem={renderItem}
8      useSnap={true}
9      itemSpacing={16} // 16px spacing between items
10    />
11  );
12}

initialIndex (default: 0)

Sets the initial index value.

dismissThreshold (default: 80)

dismissThreshold controls when onDismiss is called by applying a threshold value during vertical gestures.

resistance (default: 2)

resistance controls the range of vertical movement by applying resistance during vertical gestures.

maxZoomScale (default: 2)

Controls the maximum zoom scale multiplier.

Performance Optimization Tips

• Wrap the renderItem function with useCallback to prevent unnecessary re-renders.
• For large images, we recommend using FastImage or expo-image.
• For handling many images, we recommend using FlashList.
• Test on actual devices (performance may be limited in simulators).

Contributing

For details on how to contribute to the project and set up the development environment, please refer to the Contributing Guide.

License

MIT