react-image-utilities

React Image Utilities

A powerful and flexible React component library for image manipulation, providing a comprehensive suite of tools for cropping, compressing, resizing, format conversion, and applying visual effects to images in your web applications.

🚀 Features

• 📏 Image Cropping: Interactive cropping with resizable crop area and aspect ratio control
• 🗜️ Image Compression: Smart compression with quality control and size limits
• ↔️ Image Resizing: Flexible resizing with multiple modes and aspect ratio preservation
• 🔄 Format Conversion: Convert between popular image formats (JPEG, PNG, WebP, GIF)
• ✨ Visual Effects: Apply professional-grade effects and filters
• 📱 Responsive: Works seamlessly across different screen sizes
• 🔒 Type-Safe: Written in TypeScript with full type definitions
• 🎨 Customizable: Extensive styling and configuration options

📦 Installation

npm install react-image-utilities
# or
yarn add react-image-utilities
# or
pnpm add react-image-utilities

💻 Usage

Image Cropping

import { ImageCrop } from 'react-image-utilities';

function App() {
  const handleCropComplete = (croppedBlob: Blob) => {
    const url = URL.createObjectURL(croppedBlob);
    console.log('Cropped image URL:', url);
  };

  return (
    <ImageCrop
      image="/path/to/image.jpg" // Can be a File, Blob, or URL string
      width={300}
      height={200}
      aspectRatio={1.5}
      allowResize={true}
      showGrid={true}
      onProcessingComplete={handleCropComplete}
      onError={(error) => console.error('Crop error:', error)}
    />
  );
}

Image Compression

import { ImageCompress } from 'react-image-utilities';

function App() {
  const handleCompressionComplete = (compressedBlob: Blob) => {
    console.log('Compressed size:', compressedBlob.size);
  };

  return (
    <ImageCompress
      image="/path/to/image.jpg"
      quality={75}
      maxSizeMB={1}
      showProgress={true}
      onCompressProgress={(progress) => console.log(`${progress}%`)}
      onProcessingComplete={handleCompressionComplete}
      onError={(error) => console.error('Compression error:', error)}
    />
  );
}

Image Resizing

import { ImageResize } from 'react-image-utilities';

function App() {
  return (
    <ImageResize
      image="/path/to/image.jpg"
      width={800}
      height={600}
      maintainAspectRatio={true}
      resizeMode="contain"
      onProcessingComplete={(resizedBlob) => {
        console.log('Resized image:', resizedBlob);
      }}
    />
  );
}

Format Conversion

import { ImageFormat } from 'react-image-utilities';

function App() {
  return (
    <ImageFormat
      image="/path/to/image.jpg"
      format="webp"
      quality={80}
      onProcessingComplete={(convertedBlob) => {
        console.log('Converted image:', convertedBlob);
      }}
    />
  );
}

Visual Effects

import { ImageEffects } from 'react-image-utilities';

function App() {
  return (
    <ImageEffects
      image="/path/to/image.jpg"
      effect="grayscale"
      intensity={75}
      onProcessingComplete={(processedBlob) => {
        console.log('Processed image:', processedBlob);
      }}
    />
  );
}

📚 API Reference

Common Props

All components share these base props:

Prop	Type	Description
image	File | Blob | string	The source image (File, Blob, or URL)
onProcessingComplete	(processedImage: Blob) => void	Callback with processed image
onError	(error: Error) => void	Error handling callback
className	string	CSS class name
style	React.CSSProperties	Inline styles
validateInput	boolean	Enable input validation
onValidationError	(error: ValidationError) => void	Validation error callback

ImageCrop

Prop	Type	Default	Description
width	number	Required	Crop area width
height	number	Required	Crop area height
aspectRatio	number	undefined	Lock aspect ratio
allowResize	boolean	true	Enable resize handles
showGrid	boolean	true	Show grid overlay
gridColor	string	'rgba(255,255,255,0.8)'	Grid line color

ImageCompress

Prop	Type	Default	Description
quality	number	80	Compression quality (0-100)
maxSizeMB	number	undefined	Max file size in MB
showProgress	boolean	true	Show progress bar
onCompressProgress	(progress: number) => void	undefined	Progress callback

ImageResize

Prop	Type	Default	Description
width	number	Required	Target width
height	number	Required	Target height
maintainAspectRatio	boolean	true	Preserve aspect ratio
resizeMode	'contain' | 'cover' | 'stretch'	'contain'	Resize behavior

ImageFormat

Prop	Type	Default	Description
format	'jpeg' | 'png' | 'webp' | 'gif'	Required	Target format
quality	number	80	Output quality

ImageEffects

Prop	Type	Default	Description
effect	EffectType	Required	Effect to apply
intensity	number	100	Effect strength
blurRadius	number	undefined	Blur amount

🔧 Error Handling

Error Types

type ImageProcessingErrorType =
  | 'INVALID_INPUT'
  | 'UNSUPPORTED_FORMAT'
  | 'COMPRESSION_FAILED'
  | 'RESIZE_FAILED'
  | 'FORMAT_CONVERSION_FAILED'
  | 'EFFECT_APPLICATION_FAILED';

Example with Error Handling

import { ImageCompress, ValidationError } from 'react-image-utilities';

function App() {
  return (
    <ImageCompress
      image={imageFile}
      quality={75}
      validateInput={true}
      onError={(error) => {
        if (error.type === 'COMPRESSION_FAILED') {
          console.error('Compression failed:', error.message);
        }
      }}
      onValidationError={(error) => {
        console.error('Validation failed:', error.message);
      }}
      retryOnError={true}
      maxRetries={3}
    />
  );
}

🌐 Browser Compatibility

Feature Detection

import { checkBrowserSupport } from 'react-image-utilities';

const support = checkBrowserSupport();
if (!support.webp) {
  console.warn('WebP format not supported');
}

Minimum Browser Versions

• Chrome: 79+
• Firefox: 73+
• Safari: 14+
• Edge: 79+

⚡ Performance Considerations

• Image Size Limits

  • Recommended max input image size: 20MB
  • For larger images, use compression first
  • Consider using Web Workers for heavy processing

• Memory Usage

  • Images are processed in chunks when possible
  • Large images are automatically downscaled during preview
  • Resources are properly cleaned up after processing

• Processing Time

  • Compression: ~100ms - 2s depending on size
  • Resizing: ~50ms - 1s depending on dimensions
  • Effects: ~50ms - 500ms depending on complexity

🔍 Troubleshooting

Common Issues

• Image Not Loading

  • Check if the image URL is accessible
  • Verify CORS settings for remote images
  • Ensure the image format is supported

• Processing Errors

  • Check browser console for detailed error messages
  • Verify input image dimensions and format
  • Ensure sufficient memory is available

• Performance Issues

  • Reduce input image size
  • Lower quality settings for faster processing
  • Use Web Workers for heavy operations

🤝 Contributing

We welcome contributions! Please follow these steps:

• Fork the repository
• Create a feature branch
• Commit your changes
• Push to the branch
• Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/yourusername/react-image-utilities.git

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

📄 License

MIT © [Your Name]

🙋 Support

• Documentation: https://github.com/yourusername/react-image-utilities
• Issues: https://github.com/yourusername/react-image-utilities/issues
• Discord: Join our community