For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /guide/migration-from-2.x.md.
v3 is stable. See what changed
React Native Gesture Image Viewer
  • English
  • 3.x

      • 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.

      To understand how paging has changed, see How v3 Paging Works in the overview. It explains which pages are rendered and how the render window updates during page transitions, with an illustration.

      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

      The goToIndex, goToPrevious, and goToNext controller methods still work. horizontalSwipe with 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 with 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