Package Exports

smart-dropzone-react
smart-dropzone-react/components/document-upload
smart-dropzone-react/components/enterprise-upload
smart-dropzone-react/components/file-item
smart-dropzone-react/components/gallery-upload
smart-dropzone-react/components/media-upload
smart-dropzone-react/components/simple-upload
smart-dropzone-react/components/smart-dropzone
smart-dropzone-react/components/smart-dropzone-simple
smart-dropzone-react/hooks/use-upload
smart-dropzone-react/providers/cloudinary

Readme

🚀 Smart Dropzone

A production-ready React dropzone component with smart defaults, advanced features, and comprehensive provider support. Built for modern applications that need reliable file uploads with excellent user experience.

✨ Key Features

🎯 Smart Defaults - Zero configuration to get started, extensive customization available
🔄 Chunked Uploads - Handle large files with resume capability and progress tracking
🎨 Drag & Drop Reordering - Intuitive file reordering with visual feedback
🌐 Multi-Provider Support - Cloudinary, AWS S3, Supabase, and extensible architecture
♿ Accessibility First - WCAG compliant with screen reader support and keyboard navigation
🌍 Internationalization - Built-in i18n support with multiple languages
📱 Responsive Design - Works seamlessly across desktop and mobile devices
🚀 Performance Optimized - Lazy loading, tree shaking, and minimal bundle impact
🛡️ Type Safe - Full TypeScript support with comprehensive type definitions
📊 Production Ready - 83.7% test coverage with extensive edge case handling

📦 Installation

# npm
npm install smart-dropzone-react

# yarn
yarn add smart-dropzone-react

# pnpm
pnpm add smart-dropzone-react

Peer Dependencies

npm install react react-dom

React Version Support:

✅ React 18.x (Full support)
✅ React 19.x (Full support with latest features)
🔄 React 17.x (Legacy support - may have compatibility issues)

🚀 Quick Start

Zero Configuration (Cloudinary)

import { SimpleUpload } from "@tanflare/smart-dropzone";

function App() {
  return (
    <SimpleUpload
      cloudinary={{
        cloudName: "your-cloud-name",
        uploadPreset: "your-upload-preset",
      }}
      onFilesAdded={(files) => console.log("Files uploaded:", files)}
    />
  );
}

With Smart Presets

import { SmartDropzoneSimple } from "smart-dropzone-react";

// Gallery preset - optimized for images
function ImageGallery() {
  return (
    <SmartDropzoneSimple
      preset="gallery"
      cloudinary={{
        cloudName: "your-cloud-name",
        uploadPreset: "your-upload-preset",
      }}
    />
  );
}

// Document preset - optimized for files
function DocumentUpload() {
  return (
    <SmartDropzoneSimple
      preset="documents"
      cloudinary={{
        cloudName: "your-cloud-name",
        uploadPreset: "your-upload-preset",
      }}
    />
  );
}

Advanced Configuration

import { SmartDropzone, CloudinaryProvider } from "smart-dropzone-react";

function AdvancedUpload() {
  const provider = new CloudinaryProvider({
    cloudName: "your-cloud-name",
    uploadPreset: "your-upload-preset",
    defaultFolder: "uploads",
  });

  return (
    <SmartDropzone
      provider={provider}
      maxFiles={10}
      maxFileSize={50 * 1024 * 1024} // 50MB
      allowedTypes={["image/*", "application/pdf"]}
      enableReorder={true}
      enableResume={true}
      showPreview={true}
      theme="dark"
      onFilesAdded={(files) => console.log("Files uploaded:", files)}
      onError={(error) => console.error("Upload error:", error)}
      onProgress={(fileId, progress) =>
        console.log(`File ${fileId}: ${progress}%`)
      }
    />
  );
}

🎨 Available Presets

Preset	Use Case	Max Files	File Types	Features
`simple`	Basic uploads	5	`image/*`, `application/pdf`	Preview, Progress
`gallery`	Image galleries	20	`image/*`	Preview, Reorder, Thumbnails
`documents`	Document management	10	`application/`, `text/`	File info, Validation
`media`	Media content	15	`image/`, `video/`, `audio/*`	Preview, Player
`enterprise`	Large-scale uploads	50	All types	All features, Analytics

🌐 Provider Support

Cloudinary

import { CloudinaryProvider } from "smart-dropzone-react";

const provider = new CloudinaryProvider({
  cloudName: "your-cloud-name",
  uploadPreset: "your-upload-preset",
  defaultFolder: "uploads",
  // Optional: Add transformations
  transformations: {
    quality: "auto",
    fetch_format: "auto",
  },
});

AWS S3 (Coming Soon)

import { S3Provider } from "smart-dropzone-react";

const provider = new S3Provider({
  accessKeyId: "your-access-key",
  secretAccessKey: "your-secret-key",
  bucket: "your-bucket-name",
  region: "us-east-1",
});

Custom Provider

import { BaseProvider } from "smart-dropzone-react";

class CustomProvider extends BaseProvider {
  async uploadFile(file: File, options?: UploadOptions) {
    // Your custom upload logic
    return {
      id: "file-id",
      url: "https://your-cdn.com/file.jpg",
      uploadedAt: new Date(),
    };
  }

  // Implement other required methods...
}

🎯 Real-World Examples

E-commerce Product Images

import { GalleryUpload } from "smart-dropzone-react";

function ProductImageUpload({ productId }) {
  return (
    <GalleryUpload
      cloudinary={{
        cloudName: "your-cloud-name",
        uploadPreset: "product-images",
        defaultFolder: `products/${productId}`,
      }}
      maxFiles={8}
      onFilesAdded={(files) => {
        // Update product images in your database
        updateProductImages(productId, files);
      }}
      overrides={{
        showFileSize: true,
        enableReorder: true,
        theme: "light",
      }}
    />
  );
}

User Profile Avatar

import { SimpleUpload } from "@tanflare/smart-dropzone";

function AvatarUpload({ userId }) {
  return (
    <div className="w-32 h-32">
      <SimpleUpload
        cloudinary={{
          cloudName: "your-cloud-name",
          uploadPreset: "avatars",
          defaultFolder: "users/avatars",
        }}
        maxFiles={1}
        allowedTypes={["image/*"]}
        onFilesAdded={([file]) => {
          // Update user avatar
          updateUserAvatar(userId, file.url);
        }}
        overrides={{
          variant: "filled",
          size: "sm",
        }}
      />
    </div>
  );
}

Document Management

import { DocumentUpload } from "smart-dropzone-react";

function DocumentManager() {
  const [documents, setDocuments] = useState([]);

  return (
    <DocumentUpload
      cloudinary={{
        cloudName: "your-cloud-name",
        uploadPreset: "documents",
      }}
      onFilesAdded={(newFiles) => {
        setDocuments((prev) => [...prev, ...newFiles]);
        // Send to your document management system
        indexDocuments(newFiles);
      }}
      overrides={{
        maxFileSize: 100 * 1024 * 1024, // 100MB
        showFileType: true,
        showFileSize: true,
      }}
    />
  );
}

🛠️ Advanced Features

Chunked Uploads with Resume

<SmartDropzone
  provider={cloudinaryProvider}
  enableResume={true}
  chunkSize={1024 * 1024} // 1MB chunks
  onChunkProgress={(fileId, chunkIndex, totalChunks) => {
    console.log(`File ${fileId}: chunk ${chunkIndex}/${totalChunks}`);
  }}
  onResumeUpload={(fileId) => {
    console.log(`Resuming upload for ${fileId}`);
  }}
/>

Accessibility & Internationalization

<SmartDropzone
  provider={cloudinaryProvider}
  accessibility={{
    highContrast: true,
    reducedMotion: false,
    screenReaderSupport: true,
  }}
  i18n={{
    locale: "es",
    customTranslations: {
      "dropzone.dragActive": "Suelta los archivos aquí...",
    },
  }}
/>

Performance Monitoring

<SmartDropzone
  provider={cloudinaryProvider}
  enablePerformanceMonitoring={true}
  onPerformanceData={(metrics) => {
    console.log("Performance metrics:", {
      renderTime: metrics.renderTime,
      uploadSpeed: metrics.uploadSpeed,
      memoryUsage: metrics.memoryUsage,
    });
  }}
/>

🎨 Styling & Theming

Built-in Themes

// Light theme (default)
<SmartDropzone theme="light" />

// Dark theme
<SmartDropzone theme="dark" />

// Custom theme
<SmartDropzone
  theme={{
    colors: {
      primary: "#007bff",
      secondary: "#6c757d",
      success: "#28a745",
      error: "#dc3545"
    },
    borderRadius: "8px",
    spacing: "1rem"
  }}
/>

CSS Custom Properties

:root {
  --smart-dropzone-primary: #007bff;
  --smart-dropzone-border-radius: 8px;
  --smart-dropzone-transition: all 0.2s ease;
}

Tailwind CSS Integration

<SmartDropzone
  className="border-dashed border-2 border-blue-300 hover:border-blue-500 rounded-lg p-8"
  provider={provider}
/>

📚 API Reference

Components

SmartDropzone - Main component with full feature set
SmartDropzoneSimple - Simplified component with preset support
SimpleUpload - Zero-config component for basic uploads
GalleryUpload - Optimized for image galleries
DocumentUpload - Optimized for document management
MediaUpload - Optimized for media files
EnterpriseUpload - Full-featured for enterprise use

Providers

CloudinaryProvider - Cloudinary upload service
S3Provider - Amazon S3 (coming soon)
SupabaseProvider - Supabase storage (coming soon)
BaseProvider - Base class for custom providers

Hooks

useUpload - Core upload management hook
useFilePreview - File preview generation
useDragReorder - Drag and drop reordering
useAccessibility - Accessibility features

For complete API documentation, see API.md.

🧪 Testing

The package includes comprehensive tests with 83.7% coverage:

# Run tests
npm run test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run all tests (unit + e2e + type checking)
npm run test:all

🚀 Performance

Bundle Size: ~45KB gzipped (tree-shakeable)
First Paint: <100ms for initial render
Upload Performance: Optimized chunking for large files
Memory Usage: Efficient cleanup and garbage collection
Browser Support: Modern browsers (ES2020+)

🌟 Browser Support

Browser	Version
Chrome	≥88
Firefox	≥85
Safari	≥14
Edge	≥88

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/harishkhojare/smart-dropzone.git

# Install dependencies
pnpm install

# Start development
pnpm dev

# Run tests
pnpm test

# Build package
pnpm build

📄 License

🆘 Support

🏆 Sponsors

Special thanks to our sponsors and contributors who make this project possible!

Made with ❤️ by the Tanflare Team