react-native-gallery-picker-pro

MotorInc Media Picker

A comprehensive React Native media gallery picker with smooth animations, multi-select/single-select modes, crop functionality, and native iOS/Android support.

Features

• 🖼️ Modern UI - Smooth scrolling with layered animations
• 📱 Native Performance - Built with native iOS and Android modules
• ✨ Multi/Single Select - Flexible selection modes
• ✂️ Crop Functionality - Built-in image cropping with aspect ratio controls
• 🎬 Video Support - Handle both images and videos
• 🎯 Gesture Controls - Intuitive touch gestures and animations
• 📐 Aspect Ratios - Support for multiple aspect ratios (0.8, 16:9, 1:1)
• 🔄 Permission Handling - Smart permission management
• 📤 Export Options - Base64, URI, and file data support

Installation

npm install motorinc-media-picker

iOS Setup

• Add to your Podfile:

pod 'MotorincMediaPicker', :path => '../node_modules/motorinc-media-picker'

• Run:

cd ios && pod install

Android Setup

The Android module is automatically linked with React Native 0.60+.

Dependencies

Make sure you have these peer dependencies installed:

npm install react-native-gesture-handler react-native-reanimated react-native-view-shot

Follow the setup instructions for:

• react-native-gesture-handler
• react-native-reanimated

Usage

Basic Usage

import React from 'react';
import { View } from 'react-native';
import { MainPhotoGallery } from 'motorinc-media-picker';

export default function App() {
  const handleAssetSelected = (asset) => {
    console.log('Selected asset:', asset);
  };

  const handleSelectedAssetsChange = (assets) => {
    console.log('Selected assets:', assets);
  };

  return (
    <View style={{ flex: 1 }}>
      <MainPhotoGallery
        mediaType="all"
        multiSelect={true}
        maxSelectionLimit={10}
        onAssetSelected={handleAssetSelected}
        onSelectedAssetsChange={handleSelectedAssetsChange}
      />
    </View>
  );
}

Advanced Usage with Crop

import React, { useRef, useState } from 'react';
import { View, Button } from 'react-native';
import { MainPhotoGallery } from 'motorinc-media-picker';

export default function App() {
  const galleryRef = useRef(null);
  const [selectedAssets, setSelectedAssets] = useState([]);
  const [cropParams, setCropParams] = useState(new Map());

  const handleCroppedImagesReady = (croppedImages) => {
    console.log('Cropped images:', croppedImages);
  };

  const handleCropCapture = async () => {
    if (galleryRef.current) {
      await galleryRef.current.triggerCropCapture();
    }
  };

  return (
    <View style={{ flex: 1 }}>
      <MainPhotoGallery
        ref={galleryRef}
        mediaType="image"
        multiSelect={true}
        selectedAssets={selectedAssets}
        onSelectedAssetsChange={setSelectedAssets}
        showSelectedAssetsHeader={true}
        onCropParamsChange={(assetId, params) => {
          setCropParams(prev => new Map(prev.set(assetId, params)));
        }}
        existingCropParams={cropParams}
        onCroppedImagesReady={handleCroppedImagesReady}
        onAspectRatioChange={(ratio) => console.log('Aspect ratio:', ratio)}
      />
      <Button title="Capture Cropped Images" onPress={handleCropCapture} />
    </View>
  );
}

Props

MainPhotoGallery Props

Prop	Type	Default	Description
mediaType	'image' | 'video' | 'all'	'all'	Type of media to display
multiSelect	boolean	false	Enable multi-selection mode
maxSelectionLimit	number	10	Maximum number of assets that can be selected
selectedAssets	PhotoAsset[]	[]	Currently selected assets
onAssetSelected	(asset: PhotoAsset) => void	-	Callback when a single asset is selected
onSelectedAssetsChange	(assets: PhotoAsset[]) => void	-	Callback when selected assets change
showSelectedAssetsHeader	boolean	false	Show cropping header for selected assets
hideSelectionHeader	boolean	false	Hide the selection mode header
onCropParamsChange	(assetId: string, params: CropParams | null) => void	-	Callback for crop parameter changes
existingCropParams	Map<string, CropParams>	-	Existing crop parameters
onAspectRatioChange	(ratio: number) => void	-	Callback for aspect ratio changes
onCroppedImagesReady	(images: Array<{assetId: string, dataUri: string}>) => void	-	Callback when cropped images are ready
onCancel	() => void	-	Cancel button callback
onNext	(assets: PhotoAsset[]) => void	-	Next button callback
renderPermissionDeniedState	(onRequest?: () => void) => React.ReactNode	-	Custom permission denied state

Types

PhotoAsset

interface PhotoAsset {
  id: string;
  uri: string;
  filename: string;
  width: number;
  height: number;
  creationDate: number;
  mediaType: 'image' | 'video';
  duration?: number; // For videos
}

CropParams

interface CropParams {
  x: number;
  y: number;
  width: number;
  height: number;
  scale: number;
  aspectRatio: number;
}

SelectedImage

interface SelectedImage {
  uri: string;
  fileName: string;
  fileSize: number;
  width: number;
  height: number;
  type: string;
  id: string;
  base64: string;
}

Layered Scroll Behavior

The gallery implements smooth layered scroll behavior:

• Scroll Up: First hides the header section, then allows grid scrolling
• Scroll Down: Grid scrolls down immediately, regardless of header position
• Header Drag: Can always drag header up/down to show/hide sections
• Smooth Animations: Cubic easing for natural feel

Permissions

iOS

Add to your Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs access to photo library to select images</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>This app needs access to save images to photo library</string>

Android

Add to your AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

MIT

Support

If you like this project, please consider giving it a ⭐ on GitHub!