# React Native Gesture Image Viewer ## Guide - [Overview](/2.x/guide/getting-started/overview.md): 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](/2.x/guide/getting-started/installation.md): Minimum Requirements - [Quick Start](/2.x/guide/getting-started/quick-start.md) - [AI](/2.x/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 1.x to 2.x](/2.x/guide/migration-from-1.x.md) - [Performance Optimization Tips](/2.x/guide/performance-optimization-tips.md): Wrap the renderItem function with useCallback to prevent unnecessary re-renders. Avoid rebuilding unchanged data. Passing a new array is supported and is the correct way to publish list changes. In a parent that rerenders frequently, however, rebuilding an equivalent array can repeat viewer and dimension-reconciliation work. Pass the existing array when no transformation is needed, and memoize only genuinely derived data. Do not mutate data in place. Replace the array when its contents change: For large images, we recommend using expo-image or FastImage. For handling many images, we recommend using FlashList. FlashList Performance Guide Test on actual devices (performance may be limited in simulators). - [Basic Usage](/2.x/guide/usage/basic-usage.md) - [Custom Components](/2.x/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](/2.x/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](/2.x/guide/usage/gesture-viewer-props.md): renderItem renderItem renders each item in data and receives isActive and setItemDimensions through its third argument: renderItem(item, index, { isActive, setItemDimensions }). Use isActive for work that should run only on the active item, such as video playback. See renderItem active state (isActive) for behavior and examples. Call setItemDimensions({ width, height }) after rendered content dimensions become available. See the item dimensions guide for examples and call timing. 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. enableSnapMode (default: false) Enables snap scrolling mode. false (default): Paging mode (pagingEnabled: true)Scrolls by full screen size incrementstrue: Snap mode (snapToInterval auto-calculated)snapToInterval is automatically calculated based on width and itemSpacing valuesUse this option when you need item spacing itemSpacing (default: 0) Sets the spacing between items in pixels. Only applied when enableSnapMode is true. 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 getItemDimensions Returns natural/source dimensions for an item when they are already known. Runtime dimensions reported from renderItem with setItemDimensions take precedence. See the item dimensions guide for examples. getItemKey Returns a stable logical key for an item when the same content may be recreated as a new object in the same slot. Use it with runtime setItemDimensions values. See the item dimensions guide for details. initialIndex (default: 0) Sets the item index the viewer should display. The value is normalized against the current data length: non-finite and negative values become 0, values above the available range become the last index, and empty data resolves to 0. When initialIndex changes after the viewer is already mounted, the viewer repositions to the normalized index. maxZoomScale (default: 2) Controls the maximum zoom scale multiplier. - [GestureViewer State](/2.x/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](/2.x/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. - [Item Dimensions](/2.x/guide/usage/item-dimensions.md): GestureViewer can calculate more accurate zoom and pan bounds when it knows the natural size of the rendered content. This is most useful for contain images. Without item dimensions, the viewer keeps the previous fallback behavior and treats the full viewer cell as the content size. After fitting the natural dimensions into the viewport, content stays centered on an axis when it is smaller than the viewport and stops at the content edge when it is larger. Both width and height must be finite numbers greater than zero. - [Multi-Instance Management](/2.x/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](/2.x/guide/usage/programmatic-control.md): You can programmatically control the GestureViewer using the useGestureViewerController hook. - [Style Customization](/2.x/guide/usage/style-customization.md): You can customize the styling of GestureViewer. - [Trigger-Based Modal Animations](/2.x/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.