🔍 React Image Magnifier

🎯 A modern, powerful React component for image magnification

Built with TypeScript, featuring multiple themes, touch support, and advanced customization options

---

🎬 Demo • 📦 Installation • 🚀 Quick Start • 💡 Examples • 📖 API

---

✨ Features

🚀 Core Features	⚡ Advanced 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	🧶 yarn	📌 pnpm
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

🎨 Themed Gallery

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>
  );
}

📱 Mobile-Optimized

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"
    />
  );
}

🛍️ E-commerce Product

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

🏛️ Classic	🎯 Modern	🌙 Dark	💎 Neon
Traditional magnifying glass	Clean, minimalist blue accents	Perfect for dark mode	Vibrant pink highlights
<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)

Prop	Type	Default	Description
imageSrc	string	required	Image source URL
imageAlt	string	-	Alt text for accessibility
imageWidth	number	500	Image width in pixels
imageHeight	number	500	Image height in pixels
magnifierSize	number	300	Magnifier lens size
zoomLevel	number	2.5	Zoom multiplier
disabled	boolean	false	Disable magnification

ReactImageMagnifierAdvanced

🔧 View Advanced Props

Prop	Type	Default	Description
theme	'classic' | 'modern' | 'dark' | 'neon'	'classic'	Built-in theme
customTheme	Partial<MagnifierTheme>	-	Custom theme overrides
position	'follow' | 'fixed-*'	'follow'	Magnifier positioning
cursorStyle	'crosshair' | 'zoom-in' | 'grab' | 'pointer'	'crosshair'	Cursor style
showZoomControls	boolean	false	Show +/- buttons
showMiniMap	boolean	false	Show navigation map
enableKeyboard	boolean	true	Keyboard shortcuts
enableTouch	boolean	true	Touch/gesture support
minZoom	number	1.5	Minimum zoom level
maxZoom	number	5	Maximum zoom level
watermark	string | ReactNode	-	Watermark content
overlayContent	ReactNode	-	Custom overlay
onMagnifierShow	() => void	-	Show callback
onMagnifierHide	() => void	-	Hide callback
onZoomChange	(zoom: number) => void	-	Zoom change callback

---

⌨️ Controls

🖱️ Mouse/Keyboard	📱 Touch Gestures
• 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

🎣 Custom Hooks

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
}

🌐 Context Usage

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

❓ Common Issues & Solutions

🔍 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'

⚛️ Framework Integration

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

---