react-native-zero-permission-picker

v0.1.3

Published

a month ago

React Native file & media picker with ZERO permissions. Android Photo Picker (API 33+), iOS PHPicker, and SAF fallback. Pick images, videos, PDFs, and documents without storage permissions.

React Native Zero Permission Picker

React Native image, video, and document picker with ZERO permissions. Uses Android Photo Picker (API 33+), iOS PHPicker, and Storage Access Framework (SAF) for seamless, privacy-friendly selection.

⚡ Installation

# Install the package
npm install react-native-zero-permission-picker

# iOS setup
cd ios && pod install && cd ..

# Ready to use!

import { pickMedia, pickFiles } from 'react-native-zero-permission-picker';

// Pick images with zero permissions
const images = await pickMedia('image', { multiple: true });

🎯 Why choose this over other pickers?

🚫 Zero permissions: No storage/photo/video permission prompts
📱 Modern APIs: Android Photo Picker (API 33+) & iOS PHPicker
🔄 Compatible: SAF fallback for Android ≤12, UIImagePickerController for iOS 15
🧩 Simple API: Tiny surface area with sensible defaults
⚡ Production ready: TypeScript types, validation, tests

Looking for: “react native image picker”, “react native document picker”, or “android 13 photo picker”? This module provides a single, permissionless API that covers those use‑cases using platform system pickers.

📋 Table of Contents

✨ Features

🚫 Zero permissions – no storage/photo/video prompts
📱 Modern APIs – Android Photo Picker + iOS PHPicker
🔄 Backwards compatible – SAF on Android ≤12, UIImagePickerController on iOS 15
🎯 Multiple Selection - Pick multiple files at once
🖼️ Image Processing - Optional compression and EXIF stripping
📊 Rich Metadata - File size, dimensions, duration, MIME type
💾 File Caching - Automatic cache management
🔧 TypeScript - Full type safety
⚡ Lightweight - Minimal dependencies

Compared to popular alternatives

react-native-image-picker: requires permissions for some flows; this uses system photo picker with scoped access.
react-native-document-picker: great for documents; this unifies media + docs in one minimal API with modern platform pickers.

📱 Screenshots

App Interface

| Main Screen | Selected Items | |-------------|----------------| | | |

The app provides a clean interface for selecting files with zero permissions required.

🚀 Quick Start

Installation

# Install the package
npm install react-native-zero-permission-picker

# Or with yarn
yarn add react-native-zero-permission-picker

# Or with pnpm
pnpm add react-native-zero-permission-picker

iOS Setup

# Navigate to iOS directory and install pods
cd ios && pod install && cd ..

# For Expo projects
npx expo install react-native-zero-permission-picker

Android Setup

# No additional setup required for Android
# The package automatically configures native modules

Basic Usage

import { pickMedia, pickFiles } from 'react-native-zero-permission-picker';

// Pick images with zero permissions
const images = await pickMedia('image', {
  multiple: true,
  copyToCache: true,
  stripEXIF: true,
  compressImage: {
    quality: 0.8,
    maxWidth: 1920,
    maxHeight: 1920,
  },
});

// Pick videos without storage permissions
const videos = await pickMedia('video', {
  multiple: true,
  copyToCache: true,
});

// Pick any files using system picker
const files = await pickFiles('any', {
  multiple: true,
  copyToCache: true,
});

📖 API Reference

`pickMedia(kind, options)`

Pick images, videos, or mixed media.

Parameters:

kind: 'image' | 'video' | 'mixed' - Type of media to pick
options: PickMediaOptions - Configuration options

Returns: Promise<PickedItem[]>

Example:

const items = await pickMedia('image', {
  multiple: true,
  copyToCache: true,
  stripEXIF: true,
  compressImage: {
    quality: 0.8,
    maxWidth: 1920,
    maxHeight: 1920,
  },
});

`pickFiles(kind, options)`

Pick documents and files.

Parameters:

kind: 'any' | 'pdf' | 'video' - Type of files to pick
options: PickFilesOptions - Configuration options

Returns: Promise<PickedItem[]>

Example:

const pdfs = await pickFiles('pdf', {
  multiple: true,
});

`isSystemPhotoPickerAvailable()`

Check if the system photo picker is available.

Returns: Promise<boolean>

`clearCachedFiles()`

Clear all cached files.

Returns: Promise<void>

🔧 Options

PickMediaOptions

interface PickMediaOptions {
  multiple?: boolean;           // Allow multiple selection
  copyToCache?: boolean;        // Copy files to app cache
  stripEXIF?: boolean;          // Remove EXIF data (images only)
  compressImage?: {             // Image compression (images only)
    quality: number;            // 0.0 to 1.0
    maxWidth: number;
    maxHeight: number;
  };
}

PickFilesOptions

interface PickFilesOptions {
  multiple?: boolean;           // Allow multiple selection
}

📊 Return Value

PickedItem

interface PickedItem {
  id: string;                   // Unique identifier
  uri: string;                  // File URI
  displayName: string;          // Original filename
  mimeType: string;             // MIME type
  size: number;                 // File size in bytes
  width?: number;               // Image width (images only)
  height?: number;              // Image height (images only)
  durationMs?: number;          // Video duration (videos only)
  exifStripped?: boolean;       // EXIF was removed
}

🎯 Platform Support

iOS Support

| iOS Version | Picker API | Features | Permissions Required | |-------------|------------|----------|---------------------| | iOS 16+ | PHPickerViewController | Modern picker, multiple selection, scoped access | ❌ None | | iOS 15 | UIImagePickerController | Single selection, basic picker | ❌ None | | iOS 14- | ❌ Not Supported | - | - |

iOS Features:

✅ Zero Permissions - No photo library or storage permissions needed
✅ Modern PHPicker - iOS 16+ uses the latest system picker
✅ Backward Compatible - Falls back to UIImagePickerController on iOS 15
✅ Multiple Selection - Pick multiple files at once (iOS 16+)
✅ Scoped Access - Only access user-selected files
✅ TypeScript Support - Full type definitions included

Android Support

| Android Version | Picker API | Features | Permissions Required | |-----------------|------------|----------|---------------------| | Android 13+ | Photo Picker | Modern picker, multiple selection | ❌ None | | Android ≤12 | Storage Access Framework | Document picker, file access | ❌ None | | Android <21 | ❌ Not Supported | - | - |

Android Features:

✅ Zero Permissions - No storage or media permissions needed
✅ Modern Photo Picker - Android 13+ uses the latest system picker
✅ Storage Access Framework - Android ≤12 uses SAF for file access
✅ Multiple Selection - Pick multiple files at once
✅ Scoped Access - Only access user-selected files
✅ TypeScript Support - Full type definitions included

📱 Examples

Display Images

import { Image } from 'react-native';

const images = await pickMedia('image', { multiple: true });

images.forEach(item => (
  <Image 
    source={{ uri: item.uri }} 
    style={{ width: 200, height: 200 }} 
  />
));

Upload Files

const files = await pickFiles('any', { multiple: true, copyToCache: true });

for (const file of files) {
  const formData = new FormData();
  formData.append('file', {
    uri: file.uri,
    type: file.mimeType,
    name: file.displayName,
  });
  
  await fetch('https://api.example.com/upload', {
    method: 'POST',
    body: formData,
  });
}

Image Grid

import { FlatList, Image } from 'react-native';

<FlatList
  data={images}
  numColumns={3}
  renderItem={({ item }) => (
    <Image 
      source={{ uri: item.uri }} 
      style={{ width: 100, height: 100 }} 
    />
  )}
/>

🛠️ Development

Building

npm run build

Type Checking

npm run type-check

Linting

npm run lint

📄 License

MIT - see LICENSE for details.

🔎 Discoverability (search terms)

React Native image picker, React Native file picker, React Native document picker, Android 13 Photo Picker, iOS PHPicker, Storage Access Framework (SAF), permissionless picker, no storage permission, gallery picker, media picker, UIDocumentPicker.

🤝 Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📞 Support

🙏 Acknowledgments

Android Photo Picker API
iOS PHPickerViewController
React Native Community
All contributors

Made with ❤️ for the React Native community