🔍 React Image Magnifier

✨ Features

• 🔍 Smooth Magnification - High-performance zoom
• 🎨 4 Built-in Themes - Classic, Modern, Dark, Neon
• 📱 Touch Support - Pinch-to-zoom gestures
• ⌨️ Keyboard Navigation - +/- zoom, ESC hide
• 🎯 Smart Positioning - Follow cursor or fixed
• 🖱️ Multiple Cursors - Crosshair, zoom-in, etc

• 🎛️ Zoom Controls - Interactive +/- buttons
• 🗺️ Mini Map - Navigation overview
• 🏷️ Watermarks - Text or component overlays
• 🎭 Custom Themes - Full color customization
• ♿ Accessibility - ARIA support, screen readers
• 🔧 TypeScript - Complete type definitions

🎬 Demo

// ✨ Just works out of the box!
import { ReactImageMagnifier } from '@hammadxcm/image-magnifier';

<ReactImageMagnifier
  imageSrc="/your-amazing-image.jpg"
  imageWidth={500}
  imageHeight={400}
/>

🎯 Hover over images to see the magnification effect in action

📦 Installation

npm install @hammadxcm/image-magnifier

yarn add @hammadxcm/image-magnifier

pnpm add @hammadxcm/image-magnifier

🚀 Quick Start

Basic Usage

import { ReactImageMagnifier } from '@hammadxcm/image-magnifier';

function ProductImage() {
  return (
    <ReactImageMagnifier
      imageSrc="/product.jpg"
      imageAlt="Product showcase"
      imageWidth={600}
      imageHeight={400}
      magnifierSize={200}
      zoomLevel={2.5}
    />
  );
}

Advanced Usage with Provider

import { 
  MagnifierProvider, 
  ReactImageMagnifierAdvanced 
} from '@hammadxcm/image-magnifier';

function App() {
  return (
    <MagnifierProvider theme="modern" performanceMode={false}>
      <ReactImageMagnifierAdvanced
        imageSrc="/hero-image.jpg"
        theme="modern"
        showZoomControls={true}
        showMiniMap={true}
        enableTouch={true}
        watermark="© 2024 Your Brand"
      />
    </MagnifierProvider>
  );
}

💡 Examples

import { ReactImageMagnifierAdvanced, MagnifierProvider } from '@hammadxcm/image-magnifier';

function ThemedGallery() {
  return (
    <MagnifierProvider>
      <div className="grid grid-cols-2 gap-4">
        {/* Modern Theme */}
        <ReactImageMagnifierAdvanced
          imageSrc="/image1.jpg"
          theme="modern"
          showZoomControls={true}
          position="follow"
          cursorStyle="zoom-in"
        />
        
        {/* Dark Theme */}
        <ReactImageMagnifierAdvanced
          imageSrc="/image2.jpg"
          theme="dark"
          showMiniMap={true}
          position="fixed-top-right"
          enableTouch={true}
        />
      </div>
    </MagnifierProvider>
  );
}

function MobileGallery() {
  return (
    <ReactImageMagnifierAdvanced
      imageSrc="/mobile-image.jpg"
      enableTouch={true}
      showZoomControls={true}
      theme="modern"
      minZoom={1.5}
      maxZoom={4}
      onZoomChange={(zoom) => console.log(`Zoom: ${zoom}x`)}
      watermark="© 2024 Brand"
    />
  );
}

function ProductShowcase() {
  return (
    <ReactImageMagnifierAdvanced
      imageSrc="/product.jpg"
      theme="classic"
      showZoomControls={true}
      showMiniMap={true}
      watermark="Premium Quality ✨"
      overlayContent={
        <div className="absolute top-4 left-4 bg-red-500 text-white px-2 py-1 rounded">
          🔥 Sale 50% OFF
        </div>
      }
      onMagnifierShow={() => console.log('User examining product')}
    />
  );
}

🎨 Themes

Built-in Theme Showcase

<ReactImageMagnifierAdvanced
  theme="classic"
  // Warm, traditional styling
/>

<ReactImageMagnifierAdvanced
  theme="modern"
  // Clean blue accents
/>

<ReactImageMagnifierAdvanced
  theme="dark"
  // Subtle dark highlights
/>

<ReactImageMagnifierAdvanced
  theme="neon"
  // Pink/purple vibrancy
/>

🎨 Custom Themes

Create your own unique styling:

const customTheme = {
  borderColor: 'rgba(255, 0, 0, 0.8)',
  borderWidth: 2,
  shadowColor: 'rgba(255, 0, 0, 0.3)',
  handleColor: 'rgba(255, 0, 0, 0.9)',
  gripColor: 'rgba(200, 0, 0, 0.9)',
  backdropBlur: true,
};

<ReactImageMagnifierAdvanced
  customTheme={customTheme}
  magnifierSize={250}
/>

📖 API

ReactImageMagnifier (Basic)

ReactImageMagnifierAdvanced

⌨️ Controls

• Hover - Show magnifier
• + or = - Zoom in
• - - Zoom out
• Escape - Hide magnifier

• Tap & Hold - Show magnifier
• Drag - Move view area
• Pinch - Zoom in/out
• Double Tap - Quick zoom

🚀 Performance

Multiple Images Optimization

<MagnifierProvider performanceMode={true}>
  {images.map(image => (
    <ReactImageMagnifierAdvanced
      key={image.id}
      {...image}
      performanceMode={true}
    />
  ))}
</MagnifierProvider>

Performance Features

• ⚡ Single Active Magnifier - Only one renders at a time
• 🎯 60fps Throttling - Smooth with rapid movements
• 🧠 Smart Re-rendering - Optimized React patterns
• 📦 Tree Shaking - Import only what you need

♿ Accessibility

Built with accessibility in mind:

• 🔊 Screen Readers - Full ARIA label support
• ⌨️ Keyboard Navigation - Complete keyboard control
• 🎯 Focus Management - Proper tab order
• 🌗 High Contrast - Works with system preferences

🔧 Advanced Usage

import { useMagnifier, useTouch } from '@hammadxcm/image-magnifier';

function CustomMagnifier() {
  const magnifierProps = useMagnifier({
    magnifierSize: 200,
    zoomLevel: 3,
    smoothAnimations: true,
  });
  
  const touchProps = useTouch({
    enabled: true,
    minZoom: 1,
    maxZoom: 5,
    onGesture: (gesture) => {
      console.log('Touch gesture:', gesture);
    },
  });
  
  // Your custom implementation
}

import { useMagnifierContext } from '@hammadxcm/image-magnifier';

function ThemeSelector() {
  const { globalSettings, updateGlobalSettings } = useMagnifierContext();
  
  return (
    <select 
      value={globalSettings.theme}
      onChange={(e) => updateGlobalSettings({ theme: e.target.value })}
    >
      <option value="classic">🏛️ Classic</option>
      <option value="modern">🎯 Modern</option>
      <option value="dark">🌙 Dark</option>
      <option value="neon">💎 Neon</option>
    </select>
  );
}

🐛 Troubleshooting

🔍 Magnifier not showing

• ✅ Ensure imageSrc is valid and loads successfully
• ✅ Check that disabled prop is not set to true
• ✅ Verify image dimensions are set correctly

📱 Touch not working on mobile

• ✅ Check that enableTouch is true
• ✅ Ensure touchEnabled is enabled in MagnifierProvider
• ✅ Test on actual device, not desktop browser

⚡ Performance issues with multiple images

• ✅ Enable performanceMode in MagnifierProvider
• ✅ Use performanceMode={true} on individual components
• ✅ Consider lazy loading for large galleries

🔷 TypeScript errors

• ✅ Ensure React 18+ or 19+ is installed
• ✅ Check that all required props are provided
• ✅ Import types: import type { ReactImageMagnifierAdvancedProps } from '@hammadxcm/image-magnifier'

Next.js

import dynamic from 'next/dynamic';

const ReactImageMagnifier = dynamic(
  () => import('@hammadxcm/image-magnifier').then(mod => mod.ReactImageMagnifier),
  { ssr: false }
);

function ProductPage() {
  return (
    <ReactImageMagnifier
      imageSrc="/product.jpg"
      imageWidth={600}
      imageHeight={400}
    />
  );
}

🤝 Contributing

Quick Contributions

• 🐛 Report bugs
• 💡 Request features
• 📖 Improve documentation
• 🎨 Create custom themes

Development Setup

# Clone the repository
git clone https://github.com/hammadxcm/react-image-magnifier.git

# Install dependencies  
npm install

# Build the package
npm run build

# Run tests
npm test

🔮 Roadmap

🎯 Coming Soon

• [ ] 🎥 Video Magnification - Support for video elements
• [ ] 🌐 3D Image Support - WebGL-based exploration
• [ ] 🤖 AI-Powered Features - Smart zoom region detection
• [ ] 🎨 More Themes - Community-requested designs
• [ ] ✨ Animation Presets - Pre-built configurations

📊 Stats

📄 License

ISC License - see LICENSE file for details.

💬 Support & Community

Get Help

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📖 Documentation: Complete Guide

Show Your Support

• ⭐ Star the repository to show your support
• 🐦 Share on social media
• 📝 Write a blog post about your experience

🎉 Thank you for using React Image Magnifier! 🎉

Made with ❤️ by hammadxcm and the amazing open-source community

Crafted with passion • Built for developers • Enhanced by community