React Smart Image Uploader

🚀 A powerful and customizable image uploader component for React with cropping, compression, and session persistence features.

Features

• ✨ Easy to use: Simple API with sensible defaults
• 🖼️ Image cropping: Circle and square cropping with customizable dimensions
• 🗜️ Image compression: Built-in compression with quality control
• 💾 Session persistence: Keep uploaded files across page refreshes
• 🎨 Fully customizable: Replace the default UI with your own components
• 📱 Responsive: Works great on desktop and mobile
• 🔧 TypeScript: Full TypeScript support with comprehensive types
• 🌐 Universal: Works with any React application
• 📦 Lightweight: Minimal dependencies

Installation

npm install react-smart-image-uploader

or

yarn add react-smart-image-uploader

Quick Start

import React, { useState } from 'react';
import { ImageUploader, ProcessedImage } from 'react-smart-image-uploader';

function App() {
  const [files, setFiles] = useState<ProcessedImage[]>([]);

  return (
    <div>
      <ImageUploader
        multiple
        onFilesChange={setFiles}
        accept="image/*"
        maxFiles={5}
        maxSize={5 * 1024 * 1024} // 5MB
      />
      
      <div>
        <h3>Uploaded Files:</h3>
        {files.map((file, index) => (
          <div key={index}>
            <img src={file.url} alt={file.file.name} width={100} />
            <p>{file.file.name}</p>
          </div>
        ))}
      </div>
    </div>
  );
}

API Reference

ImageUploader Props

Prop	Type	Default	Description
multiple	boolean	false	Allow multiple file selection
accept	string	undefined	File types to accept (e.g., "image/*")
maxFiles	number	10	Maximum number of files
maxSize	number	5242880	Maximum file size in bytes (5MB)
disabled	boolean	false	Disable the uploader
compression	CompressionConfig | null	{ quality: 0.2, maxWidth: 1920, maxHeight: 1080 }	Image compression settings (pass null to disable)
crop	CropConfig	undefined	Image cropping settings
session	SessionConfig	undefined	Session persistence settings
customUI	(props: CustomUIProps) => ReactNode	undefined	Custom UI renderer
showPreview	boolean	true	Show file previews
showProgress	boolean	false	Show upload progress
className	string	undefined	CSS class name
style	CSSProperties	undefined	Inline styles
uploadText	string	"Click to upload or drag and drop"	Upload area text
dragText	string	"Drop files here"	Drag active text
errorText	object	See below	Error messages
onFilesChange	(files: ProcessedImage[]) => void	undefined	Files change callback
onError	(error: string) => void	undefined	Error callback
onProgress	(progress: number) => void	undefined	Progress callback
onCrop	(croppedImage: ProcessedImage) => void	undefined	Crop complete callback

CompressionConfig

interface CompressionConfig {
  quality: number; // 0.1 to 1.0
  maxWidth?: number;
  maxHeight?: number;
  convertSize?: number; // Convert to JPEG if larger than this size
}

CropConfig

interface CropConfig {
  enabled: boolean;
  shape: 'circle' | 'square';
  width?: number;
  height?: number;
  aspect?: number; // width/height ratio
}

SessionConfig

interface SessionConfig {
  enabled: boolean;
  key?: string; // localStorage key
  clearOnUnmount?: boolean;
}

Usage Examples

Basic Image Upload

import { ImageUploader } from 'react-smart-image-uploader';

function BasicUpload() {
  return (
    <ImageUploader
      accept="image/*"
      onFilesChange={(files) => console.log('Files:', files)}
    />
  );
}

Multiple Files with Compression

function MultipleUpload() {
  return (
    <ImageUploader
      multiple
      maxFiles={10}
      compression={{
        quality: 0.8,
        maxWidth: 1920,
        maxHeight: 1080,
      }}
      onFilesChange={(files) => {
        files.forEach(file => {
          console.log('Base64:', file.base64);
          console.log('Blob:', file.blob);
        });
      }}
    />
  );
}

Disable Compression

function NoCompressionUpload() {
  return (
    <ImageUploader
      multiple
      compression={null} // Disable compression entirely
      onFilesChange={(files) => {
        // Files will be uploaded without compression
        console.log('Original files:', files);
      }}
    />
  );
}

Image Cropping

function CroppingUpload() {
  return (
    <ImageUploader
      crop={{
        enabled: true,
        shape: 'circle',
        width: 200,
        height: 200,
      }}
      onCrop={(croppedImage) => {
        console.log('Cropped image:', croppedImage);
      }}
    />
  );
}

Session Persistence

function PersistentUpload() {
  return (
    <ImageUploader
      multiple
      session={{
        enabled: true,
        key: 'my-upload-session',
        clearOnUnmount: false,
      }}
      onFilesChange={(files) => {
        // Files will persist across page refreshes
        console.log('Persistent files:', files);
      }}
    />
  );
}

Custom UI

function CustomUIUpload() {
  return (
    <ImageUploader
      customUI={({ isDragActive, openFileDialog, files, removeFile }) => (
        <div className="my-custom-uploader">
          <button 
            onClick={openFileDialog}
            className={isDragActive ? 'drag-active' : ''}
          >
            {isDragActive ? 'Drop it!' : 'Click to Upload'}
          </button>
          
          <div className="file-list">
            {files.map((file, index) => (
              <div key={index} className="file-item">
                <img src={file.url} alt={file.file.name} />
                <button onClick={() => removeFile(index)}>Remove</button>
              </div>
            ))}
          </div>
        </div>
      )}
    />
  );
}

Using Ref for Programmatic Control

import { useRef } from 'react';
import { ImageUploader, ImageUploaderRef } from 'react-smart-image-uploader';

function RefExample() {
  const uploaderRef = useRef<ImageUploaderRef>(null);

  const handleClearAll = () => {
    uploaderRef.current?.clearFiles();
  };

  const handleOpenDialog = () => {
    uploaderRef.current?.openFileDialog();
  };

  const handleGetFiles = () => {
    const files = uploaderRef.current?.getFiles();
    console.log('Current files:', files);
  };

  return (
    <div>
      <ImageUploader ref={uploaderRef} multiple />
      
      <div>
        <button onClick={handleOpenDialog}>Open File Dialog</button>
        <button onClick={handleClearAll}>Clear All</button>
        <button onClick={handleGetFiles}>Get Files</button>
      </div>
    </div>
  );
}

Styling

The component uses Tailwind CSS classes by default, but you can easily customize the styling:

Using CSS Classes

<ImageUploader
  className="my-uploader"
  // ... other props
/>

.my-uploader {
  border: 2px dashed #ccc;
  border-radius: 8px;
  padding: 20px;
}

.my-uploader:hover {
  border-color: #007bff;
}

Using Inline Styles

<ImageUploader
  style={{
    border: '2px dashed #ccc',
    borderRadius: '8px',
    padding: '20px',
  }}
/>

TypeScript Support

The package is written in TypeScript and provides comprehensive type definitions:

import {
  ImageUploader,
  ProcessedImage,
  ImageUploaderProps,
  ImageUploaderRef,
  CropConfig,
  CompressionConfig,
  SessionConfig,
} from 'react-smart-image-uploader';

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Contributing

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

License

MIT © [Your Name]

Changelog

v1.0.0

• Initial release
• Image upload with drag & drop
• Image compression
• Image cropping (circle/square)
• Session persistence
• Custom UI support
• TypeScript support