v3 beta is live. Learn more
React Native Gesture Image Viewer
  • English
  • 3.x-beta

      • Migrating from 2.x to 3.x

      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.

      Migration Steps

      Remove list component props

      Delete ListComponent and listProps from GestureViewer.

      <GestureViewer
  data={images}
  renderItem={renderImage}
- ListComponent={FlatList}
- listProps={{
-   keyExtractor: (item) => item.id,
- }}
/>

      Replace snap spacing with page spacing

      enableSnapMode and itemSpacing have been removed. Use pageSpacing when you need visible space between pages.

      <GestureViewer
  data={images}
  renderItem={renderImage}
- enableSnapMode
- itemSpacing={16}
+ pageSpacing={16}
/>

      Tune the render window only when needed

      By default, v3 mounts three pages: previous, current, and next. Increase windowSize only when you need more adjacent content mounted.

      <GestureViewer data={images} renderItem={renderImage} windowSize={5} />

      Keep programmatic navigation

      goToIndex, goToPrevious, and goToNext still work. horizontalSwipe={{ enabled: false }} disables only user/mouse horizontal swipe gestures; controller navigation and autoplay remain available.

      <GestureViewer
  data={images}
  renderItem={renderImage}
- enableHorizontalSwipe={false}
+ horizontalSwipe={{ enabled: false }}
/>
      const { goToIndex } = useGestureViewerController();

goToIndex(2);
goToIndex(2, { animated: false });

      Removed Props

      2.x prop3.x replacement
      ListComponentRemoved. Paging is internal.
      listPropsRemoved. Use renderItem for content customization.
      enableSnapModeRemoved. Internal paging is always gesture-driven.
      itemSpacingpageSpacing

      Common listProps Migrations

      v3 no longer forwards props to ScrollView, FlatList, or FlashList. Move common listProps usage to the v3 viewer APIs instead:

      2.x listProps usagev3 direction
      keyExtractorRemoved. The render window owns slot keys; keep stable item identity in data and render content through renderItem.
      initialScrollIndexUse initialIndex.
      scrollEnabled, pagingEnabled, horizontal, snapToInterval, decelerationRateRemoved. Paging is gesture-owned. Use horizontalSwipe={{ enabled: false }} to lock user swipes and pageSpacing for visible page gaps.
      onScroll, onMomentumScrollEnd, onViewableItemsChangedRemoved. Use useGestureViewerState for currentIndex/totalCount; use viewer events for supported viewer interactions.
      ref.current.scrollToIndex(...)Use useGestureViewerController().goToIndex(...), goToNext(), or goToPrevious().
      windowSize, maxToRenderPerBatch, removeClippedSubviews, estimatedItemSizeReplace list virtualization tuning with windowSize. The default mounts previous/current/next only.
      showsHorizontalScrollIndicator, contentContainerStyle, list separatorsRemoved. Compose visual content inside renderItem or use pageSpacing for inter-page gaps.

      Notes

      • renderItem remains the customization point for images, videos, and custom content.
      • useGestureViewerState continues to expose currentIndex and totalCount.
      • useGestureViewerController remains the programmatic control surface.