# React Native Gesture Image Viewer ## Guide - [Overview](/3.x-beta/guide/getting-started/overview.md): This is the v3 beta documentation. The default stable documentation remains 2.x until v3 is released as stable. 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. - [Installation](/3.x-beta/guide/getting-started/installation.md): Minimum Requirements - [Quick Start](/3.x-beta/guide/getting-started/quick-start.md) - [AI](/3.x-beta/guide/getting-started/ai.md): To help AI better understand this library's features, versioned documentation, and project conventions so it can provide more accurate help during development and troubleshooting, this project provides the following capabilities: ## Others - [Migrating from 2.x to 3.x](/3.x-beta/guide/migration-from-2.x.md): Version 3 removes the consumer-supplied list paging layer. GestureViewer now owns its paging with an internal gesture-driven render window, so apps no longer need to pass ScrollView, FlatList, or FlashList into the viewer. - [Performance Optimization Tips](/3.x-beta/guide/performance-optimization-tips.md): Wrap the renderItem function with useCallback to prevent unnecessary re-renders. For large images, we recommend using expo-image or FastImage. Keep the render window small unless you need more adjacent pages mounted. The default windowSize is 3, which mounts the previous, current, and next items. Larger windows can make adjacent pages feel more ready, but they also increase render, memory, and image decode work. The library does not cap windowSize; choosing a large value is an explicit performance tradeoff. Test on actual devices (performance may be limited in simulators). - [Basic Usage](/3.x-beta/guide/usage/basic-usage.md) - [Custom Components](/3.x-beta/guide/usage/custom-components.md): 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. - [Gesture Features](/3.x-beta/guide/usage/gesture-features.md): react-native-gesture-image-viewer supports various gestures essential for viewers. Please refer to the examples below for default gesture actions. - [GestureViewer Props](/3.x-beta/guide/usage/gesture-viewer-props.md): enableLoop (default: false) Enables loop mode. When true, navigating next from the last item goes to the first item, and navigating previous from the first item goes to the last item. windowSize (default: 3) Controls how many internal render-window slots are mounted, including the current item. Values are normalized to an odd number of at least 3; for example, 4 becomes 5. There is no hard maximum. Large values intentionally mount more renderItem content, so treat them as an explicit memory, render, and image decode cost. pageSpacing (default: 0) Sets horizontal visual space between pages. The page stride is width + pageSpacing, while zoom bounds still use width and height. horizontalSwipe Controls user-driven left/right page swipe gestures. Controller navigation and autoplay remain available when disabled. Defaults: enabled: truedistanceThresholdRatio: 0.25 of viewer widthvelocityThreshold: 800 points/sec A page commits when absolute horizontal distance is strictly greater than width * distanceThresholdRatio, or absolute horizontal velocity is strictly greater than velocityThreshold. Distance and velocity use strict > OR semantics. Zero and every finite non-negative value are accepted, including distance ratios greater than 1; negative and non-finite values fall back to defaults. Disable only user/mouse horizontal gestures: Use a distance-focused configuration: Use a velocity-focused configuration: Disable user gestures while autoplay continues: autoPlay (default: false) Enables auto play mode. When true, the viewer will automatically play the next item after the specified interval. When enableLoop is enabled, the viewer will loop back to the first item after the last item.When enableLoop is disabled, the viewer will stop at the last item.When there is only one item, auto-play is disabled.When zoom or rotate gestures are detected, the auto-play will be paused. autoPlayInterval (default: 3000) Sets the interval between auto play in milliseconds. Must be a positive integer. Values below 250ms are clamped to 250ms at runtime. onSingleTap Runs when the viewer confirms a single tap. This is useful for toggling viewer chrome such as headers, footers, captions, and action buttons without overlaying another pressable on top of the viewer. May resolve slightly later when double-tap zoom is enabled because the viewer waits to confirm it is not a double tapDoes not fire for swipe, pinch, dismiss, or double-tap zoom gestures initialIndex (default: 0) Sets the initial index value. maxZoomScale (default: 2) Controls the maximum zoom scale multiplier. - [GestureViewer State](/3.x-beta/guide/usage/gesture-viewer-state.md): GestureViewer provides a state management system to track the current state of the viewer. You can use the useGestureViewerState hook to access the state of the viewer. - [Handling Viewer Events](/3.x-beta/guide/usage/handling-viewer-events.md): GestureViewer provides a way to subscribe to specific events from the viewer using the useGestureViewerEvent hook. This allows you to respond to viewer interactions such as zoom, rotation, and taps. - [Multi-Instance Management](/3.x-beta/guide/usage/multi-instance-management.md): 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. - [Programmatic Control](/3.x-beta/guide/usage/programmatic-control.md): You can programmatically control the GestureViewer using the useGestureViewerController hook. - [Style Customization](/3.x-beta/guide/usage/style-customization.md): You can customize the styling of GestureViewer. - [Trigger-Based Modal Animations](/3.x-beta/guide/usage/trigger-based-animations.md): GestureTrigger supports smooth trigger-based animations that create seamless transitions from trigger elements (like thumbnails) to the full modal view. This feature enhances user experience by maintaining visual continuity between the trigger and modal content.