Quick Start

Examples & Demo

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

Installation

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. If you haven't set it up yet, please refer to the installation guide.

npm

yarn

pnpm

bun

deno

npm install react-native-gesture-image-viewer@2

Basic Usage

react-native-gesture-image-viewer is a library focused purely on gesture interactions for complete customization.

import { useCallback, useState } from 'react';
import { ScrollView, Image, Modal, View, Text, Button, Pressable } from 'react-native';
import {
  GestureViewer,
  GestureTrigger,
  useGestureViewerController,
  useGestureViewerEvent,
  useGestureViewerState,
} from 'react-native-gesture-image-viewer';

function App() {
  const images = [...];
  const [visible, setVisible] = useState(false);
  const [selectedIndex, setSelectedIndex] = useState(0);

  const { goToIndex, goToPrevious, goToNext } = useGestureViewerController();

  const { currentIndex, totalCount } = useGestureViewerState();

  const openModal = (index: number) => {
    setSelectedIndex(index);
    setVisible(true);
  };

  const renderImage = useCallback((imageUrl: string) => {
    return <Image source={{ uri: imageUrl }} style={{ width: '100%', height: '100%' }} resizeMode="contain" />;
  }, []);

  useGestureViewerEvent('zoomChange', (data) => {
    console.log(`Zoom changed from ${data.previousScale} to ${data.scale}`);
  });

  return (
    <View>
      {images.map((uri, index) => (
        <GestureTrigger key={uri} onPress={() => openModal(index)}>
          <Pressable>
            <Image source={{ uri }} />
          </Pressable>
        </GestureTrigger>
      ))}
      <Modal transparent visible={visible}>
        <GestureViewer
          data={images}
          initialIndex={selectedIndex}
          renderItem={renderImage}
          ListComponent={ScrollView}
          onDismiss={() => setVisible(false)}
        />
        <View>
          <Button title="Prev" onPress={goToPrevious} />
          <Button title="Jump to index 2" onPress={() => goToIndex(2)} />
          <Button title="Next" onPress={goToNext} />
          <Text>{`${currentIndex + 1} / ${totalCount}`}</Text>
        </View>
      </Modal>
    </View>
  );
}

Accurate bounds for

contain content For accurate zoom and pan bounds, provide natural content dimensions with getItemDimensions, or report them after loading with setItemDimensions. See the item dimensions guide.

#Quick Start

#Examples & Demo

#Installation

#Basic Usage

Quick Start

Examples & Demo

Installation

Basic Usage