React Native Awesome Gallery

The Gallery component is the main entry point for creating an interactive image gallery in React Native. It supports zooming (pinch/double-tap), swiping between images, and looping. It uses react-native-reanimated and react-native-gesture-handler for high-performance animations and gestures.

To use it, provide a data array and a renderItem function. By default, it provides a simple image renderer, but you can customize it to render any component.

import React, { useRef } from 'react';
import Gallery, { GalleryRef } from 'react-native-awesome-gallery';

const MyGallery = () => {
  const galleryRef = useRef<GalleryRef>(null);
  const images = ['https://example.com/1.jpg', 'https://example.com/2.jpg'];

  return (
    <Gallery
      ref={galleryRef}
      data={images}
      renderItem={({ item, index, setImageDimensions }) => (
        <Image
          source={{ uri: item }}
          onLoad={(e) => {
            const { height: h, width: w } = e.nativeEvent.source;
            setImageDimensions({ height: h, width: w });
          }}
          style={{ width: '100%', height: '100%' }}
        />
      )}
    />
  );
};

The Gallery component accepts several props to control its behavior, appearance, and interaction model:

Data and Rendering

• data: T[] - Array of items to render.
• renderItem: (renderItemInfo: {item: T, index: number, setImageDimensions: Function}) => React.ReactElement - Callback to render custom image components (e.g., FastImage). Important: You must call setImageDimensions({width, height}) after the image has loaded.
• keyExtractor: (item: T, index: number) => string | number - Provides unique keys for items.
• initialIndex: number - The starting index (defaults to 0).
• numToRender: number - Number of items rendered simultaneously (defaults to 5).

Gestures and Scaling

• doubleTapEnabled: boolean - Enables/disables double tap (defaults to true).
• doubleTapScale: number - Scale factor when double tap occurs (defaults to 3).
• doubleTapInterval: number - Milliseconds between single and double tap (defaults to 500).
• pinchEnabled: boolean - Enables/disables pinch gesture (defaults to true).
• swipeEnabled: boolean - Enables/disables pan gesture (defaults to true).
• maxScale: number - Maximum scale allowed via gestures (defaults to 6).
• disableVerticalSwipe: boolean - Disables vertical swipe when scale is 1.
• disableSwipeUp: boolean - Disables swipe up when scale is 1.
• disableTransitionOnScaledImage: boolean - Prevents transitioning to next/previous image when scale > 1.
• hideAdjacentImagesOnScaledImage: boolean - Hides adjacent images when scale > 1.

Layout and Behavior

• loop: boolean - Enables infinite swiping (requires data.length > 1).
• emptySpaceWidth: number - Width of space between items (defaults to 30).
• containerDimensions: {width: number, height: number} - Dimensions of the wrapping View (defaults to useWindowDimensions() values).
• style: ViewStyle - Style for the container.

Events

• onIndexChange: (newIndex: number) => void - Called when the active item index changes.
• onScaleChange: (scale: number) => void - Called when the scale changes.
• onScaleChangeRange: {start: number, end: number} - Defines the scale range for onScaleChange calls.

When using this project within a monorepo or a library development environment (like the provided example folder), you must configure Metro to prevent multiple versions of peerDependencies from being loaded. This is achieved by:

1. Blacklisting the node_modules located at the project root to prevent Metro from resolving them.
2. Aliasing those same modules to the specific versions installed within the local example/node_modules using extraNodeModules.

This ensures that the application uses the exact versions of peer dependencies intended for the example/app context, avoiding conflicts.

const config = {
  ...defaultConfig,
  projectRoot: __dirname,
  watchFolders: [root],
  resolver: {
    ...defaultConfig.resolver,
    // 1. Block peerDependencies at the root
    blacklistRE: exclusionList(
      modules.map(
        (m) =>
          new RegExp(`^${escape(path.join(root, 'node_modules', m))}\\/.*$`)
      )
    ),
    // 2. Alias them to the local node_modules
    extraNodeModules: modules.reduce((acc, name) => {
      acc[name] = path.join(__dirname, 'node_modules', name);
      return acc;
    }, {}),
  },
};

The Gallery component accepts several props to customize its behavior and appearance:

The Gallery component provides several event handlers to respond to user interactions. Note that onTranslationYChange is a 'worklet'; and must be implemented as a Reanimated worklet for performance.

| Prop | Description | Type |
|------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|------------|
| onSwipeToClose() | Fired when user swiped to top/bottom | `Function` |
| onTranslationYChange(translationY: number, shouldClose: boolean) | `'worklet';` Fired when user is swiping vertically to close the gallery | `Worklet` |
| onTap() | Fired when user tap on image | `Function` |
| onDoubleTap(toScale: number) | Fired when user double tap on image | `Function` |
| onLongPress() | Fired when long press is detected | `Function` |
| onScaleStart(scale: number) | Fired when pinch gesture starts | `Function` |
| onScaleEnd(scale: number) | Fired when pinch gesture ends. Use case: add haptic feedback when user finished gesture with `scale > maxScale` or `scale < 1` | `Function` |
| onPanStart() | Fired when pan gesture starts | `Function` |