React Native Image Zoom Viewer

A powerful, high-performance React Native component for viewing images with native zoom capabilities. Supports both single image zoom and multiple images gallery with swipe navigation.

✨ Features

• 🔍 Native zoom implementation for optimal performance
• 👆 Pinch-to-zoom and pan gestures
• 📷 Single image mode - View and zoom individual images
• 🖼️ Gallery mode - Swipe through multiple images
• 📊 Page indicators for gallery navigation
• 🎨 Customizable headers and footers
• ⚡️ Fast image loading with ActivityIndicator
• 📱 Fully responsive design
• 💫 Smooth animations
• 🎭 Custom render props for advanced customization

📦 Installation

# Using npm
npm install @vijaykishan312/react-native-image-zoom-viewer

# Using yarn
yarn add @vijaykishan312/react-native-image-zoom-viewer

🚀 Usage

Single Image Mode

Perfect for viewing a single image with zoom capabilities:

import React, { useState } from "react";
import { View, Button } from "react-native";
import ImageZoomViewer from "@vijaykishan312/react-native-image-zoom-viewer";

const App = () => {
  const [visible, setVisible] = useState(false);

  return (
    <View>
      <Button title="View Image" onPress={() => setVisible(true)} />
      
      <ImageZoomViewer
        visible={visible}
        onRequestClose={() => setVisible(false)}
        imageSource={{ uri: "https://example.com/image.jpg" }}
        title="Beautiful Landscape"
        minScale={1.0}
        maxScale={3.0}
      />
    </View>
  );
};

Multiple Images Mode (Gallery)

Perfect for image galleries with swipe navigation:

import React, { useState } from "react";
import { View, Button } from "react-native";
import ImageZoomViewer from "@vijaykishan312/react-native-image-zoom-viewer";

const App = () => {
  const [visible, setVisible] = useState(false);
  const [currentIndex, setCurrentIndex] = useState(0);

  const images = [
    {
      uri: "https://example.com/image1.jpg",
      title: "Mountain Landscape",
    },
    {
      uri: "https://example.com/image2.jpg",
      title: "Ocean View",
    },
    {
      uri: "https://example.com/image3.jpg",
      title: "Forest Path",
    },
  ];

  return (
    <View>
      <Button title="Open Gallery" onPress={() => setVisible(true)} />
      
      <ImageZoomViewer
        visible={visible}
        onRequestClose={() => setVisible(false)}
        imageUrls={images}
        initialIndex={0}
        onIndexChange={(index) => setCurrentIndex(index)}
        showPageIndicator={true}
        minScale={1.0}
        maxScale={3.0}
      />
    </View>
  );
};

Advanced Usage with Custom Header & Footer

import React, { useState } from "react";
import { View, Text, TouchableOpacity, Share } from "react-native";
import ImageZoomViewer from "@vijaykishan312/react-native-image-zoom-viewer";

const App = () => {
  const [visible, setVisible] = useState(false);

  const images = [
    { uri: "https://example.com/image1.jpg", title: "Image 1" },
    { uri: "https://example.com/image2.jpg", title: "Image 2" },
  ];

  const renderHeader = (onClose, currentIndex, images) => (
    <View style={{ flexDirection: 'row', padding: 15 }}>
      <Text style={{ color: '#FFF', flex: 1 }}>
        {images[currentIndex]?.title}
      </Text>
      <TouchableOpacity onPress={onClose}>
        <Text style={{ color: '#FFF', fontSize: 24 }}>×</Text>
      </TouchableOpacity>
    </View>
  );

  const renderFooter = (currentIndex, images) => (
    <View style={{ padding: 20, alignItems: 'center' }}>
      <TouchableOpacity 
        onPress={() => Share.share({ url: images[currentIndex]?.uri })}
        style={{ backgroundColor: '#007AFF', padding: 12, borderRadius: 20 }}
      >
        <Text style={{ color: '#FFF' }}>Share Image</Text>
      </TouchableOpacity>
    </View>
  );

  return (
    <View>
      <ImageZoomViewer
        visible={visible}
        onRequestClose={() => setVisible(false)}
        imageUrls={images}
        renderHeader={renderHeader}
        renderFooter={renderFooter}
        backgroundColor="rgba(0, 0, 0, 0.95)"
      />
    </View>
  );
};

📋 Props

Core Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | visible | boolean | ✅ Yes | - | Controls the visibility of the modal | | onRequestClose | function | ✅ Yes | - | Callback when modal is closing |

Single Image Mode Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | imageSource | object | ✅ Yes* | - | Image source object { uri: 'url' } | | title | string | No | - | Title displayed in the header |

*Required only for single image mode

Multiple Images Mode Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | imageUrls | array | ✅ Yes* | [] | Array of image objects [{ uri, title }] or strings | | initialIndex | number | No | 0 | Initial image index to display | | onIndexChange | function | No | - | Callback when image index changes (index) => {} | | showPageIndicator | boolean | No | true | Show/hide page indicator dots |

*Required only for multiple images mode

Customization Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | renderHeader | function | No | - | Custom header renderer (onClose, currentIndex, images) => {} | | renderFooter | function | No | - | Custom footer renderer (currentIndex, images) => {} | | backgroundColor | string | No | 'rgba(0,0,0,0.9)' | Background color of the modal |

Zoom Control Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | minScale | number | No | 1.0 | Minimum zoom scale | | maxScale | number | No | 3.0 | Maximum zoom scale |

Gesture Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | enableSwipeDown | boolean | No | false | Enable swipe down to close (experimental) | | onSwipeDown | function | No | - | Callback when swiped down |

🎯 Image URL Formats

The component supports multiple image URL formats:

// Array of objects with uri and title
const images = [
  { uri: "https://example.com/image1.jpg", title: "Image 1" },
  { uri: "https://example.com/image2.jpg", title: "Image 2" },
];

// Array of objects with url (alternative)
const images = [
  { url: "https://example.com/image1.jpg", title: "Image 1" },
  { url: "https://example.com/image2.jpg", title: "Image 2" },
];

// Array of strings (URLs only)
const images = [
  "https://example.com/image1.jpg",
  "https://example.com/image2.jpg",
];

🎨 Styling Examples

Custom Background

<ImageZoomViewer
  backgroundColor="rgba(0, 0, 0, 0.95)"
  // ... other props
/>

Custom Zoom Levels

<ImageZoomViewer
  minScale={0.5}
  maxScale={5.0}
  // ... other props
/>

📱 Platform Support

• ✅ iOS
• ✅ Android
• ⚠️ Requires native modules (not compatible with Expo Go, use development builds)

🔧 Local Development

To use this package locally in your project:

# In this package directory
npm link

# In your React Native project
npm link @vijaykishan312/react-native-image-zoom-viewer

Or install directly from local path:

npm install /path/to/react-native-image-zoom-viewer-npm

📖 Example App

This package includes a full example app demonstrating both modes:

cd react-native-image-zoom-viewer-npm
npm install
npm start

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © Vijay Kishan

🔗 Links

• npm Package: @vijaykishan312/react-native-image-zoom-viewer
• GitHub: vijaykishan312/react-native-image-zoom-viewer
• Issues: Report a bug

💡 Tips

1. Performance: The component uses native modules for optimal zoom performance
2. Image Loading: Images show an ActivityIndicator while loading
3. Gallery Navigation: Swipe left/right to navigate between images in gallery mode
4. Page Indicators: Automatically shown when multiple images are present
5. Custom Renders: Use renderHeader and renderFooter for complete customization

Made with ❤️ by Vijay Kishan