@metadiv-studio/upload

A comprehensive React component library for handling file uploads with support for avatars, images, files, and videos. Built with TypeScript, Tailwind CSS, and modern React patterns.

📦 Installation

npm i @metadiv-studio/upload

🎯 What This Package Provides

This package offers four specialized upload components, each designed for specific use cases:

• AvatarUpload - Perfect for profile pictures and small circular images
• ImageUpload - Ideal for general image uploads with rectangular preview
• FileUpload - Handles any file type with size validation and file info display
• VideoUpload - Specialized for video files with preview and playback controls

All components:

• Convert files to base64 for easy storage and transmission
• Provide loading states and error handling
• Include clear/remove functionality
• Support custom styling via Tailwind CSS classes
• Are fully typed with TypeScript
• Include tooltips for better UX

🚀 Usage Examples

AvatarUpload

Perfect for profile pictures, user avatars, or any small circular image upload.

import { AvatarUpload } from '@metadiv-studio/upload';

function ProfileForm() {
  const handleAvatarUpload = (base64: string) => {
    console.log('Avatar uploaded:', base64);
    // Send to your API or store in state
  };

  return (
    <div>
      <h3>Profile Picture</h3>
      <AvatarUpload
        text="JD" // Fallback text when no image
        base64="" // Initial image (optional)
        onUpload={handleAvatarUpload}
        className="border-2 border-blue-500" // Custom styling
      />
    </div>
  );
}

ImageUpload

Great for general image uploads, product photos, or any rectangular image content.

import { ImageUpload } from '@metadiv-studio/upload';

function ProductForm() {
  const [productImage, setProductImage] = useState('');

  const handleImageUpload = (base64: string) => {
    setProductImage(base64);
    // Update your form state or send to API
  };

  return (
    <div>
      <label>Product Image</label>
      <ImageUpload
        base64={productImage}
        onUpload={handleImageUpload}
        className="w-64 h-40" // Custom dimensions
      />
    </div>
  );
}

FileUpload

Handles any file type with built-in size validation and file information display.

import { FileUpload } from '@metadiv-studio/upload';

function DocumentUpload() {
  const handleFileUpload = (base64: string, fileName?: string) => {
    console.log('File uploaded:', fileName);
    console.log('Base64 data:', base64);
    // Process the file data
  };

  return (
    <div>
      <h3>Upload Document</h3>
      <FileUpload
        accept=".pdf,.doc,.docx,.txt" // Restrict file types
        maxSize={5 * 1024 * 1024} // 5MB limit
        placeholder="Click to upload document"
        onUpload={handleFileUpload}
        className="w-full max-w-md"
      />
    </div>
  );
}

VideoUpload

Specialized for video files with preview capabilities and playback controls.

import { VideoUpload } from '@metadiv-studio/upload';

function VideoGallery() {
  const [videos, setVideos] = useState<string[]>([]);

  const handleVideoUpload = (base64: string) => {
    setVideos(prev => [...prev, base64]);
    // Store video data or send to your backend
  };

  return (
    <div>
      <h3>Upload Video</h3>
      <VideoUpload
        onUpload={handleVideoUpload}
        width="320px"
        height="240px"
        className="border-dashed border-gray-300"
      />
    </div>
  );
}

🔧 Component Props

Common Props (All Components)

| Prop | Type | Description | Default | |------|------|-------------|---------| | base64 | string | Initial file data in base64 format | "" | | onUpload | (base64: string, fileName?: string) => void | Callback when file is uploaded | - | | className | string | Additional CSS classes for styling | - |

AvatarUpload Specific

| Prop | Type | Description | Default | |------|------|-------------|---------| | text | string | Fallback text when no image is set | - |

ImageUpload Specific

| Prop | Type | Description | Default | |------|------|-------------|---------| | text | string | Fallback text when no image is set | - |

FileUpload Specific

| Prop | Type | Description | Default | |------|------|-------------|---------| | accept | string | File types to accept (e.g., ".pdf,.doc") | All files | | maxSize | number | Maximum file size in bytes | No limit | | placeholder | string | Custom placeholder text | Default text |

VideoUpload Specific

| Prop | Type | Description | Default | |------|------|-------------|---------| | width | string | Custom width for video container | "192px" | | height | string | Custom height for video container | "128px" |

🎨 Styling

All components use Tailwind CSS and can be customized using the className prop. The components follow a consistent design system with:

• Hover effects and transitions
• Loading states with animations
• Clear/remove buttons
• Responsive design
• Accessible color schemes

🔒 File Handling

• Base64 Conversion: All files are automatically converted to base64 for easy storage and transmission
• File Validation: FileUpload component includes size validation
• Type Restrictions: FileUpload and VideoUpload support file type restrictions
• Memory Management: VideoUpload properly cleans up object URLs

🚨 Dependencies

This package requires the following peer dependencies:

{
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "@metadiv-studio/translation": "^1.0.0"
  }
}

🎯 Use Cases

• User Management: Profile pictures, avatars
• E-commerce: Product images, gallery uploads
• Content Management: Document uploads, media libraries
• Social Platforms: User content, media sharing
• Admin Panels: File management, bulk uploads

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

📄 License

This project is licensed under the MIT License.