Media Library S3

A powerful React component library for media management with S3 integration. Features folder organization, drag-and-drop uploads, search and filtering, and a clean modal interface.

Features

• 📁 Folder Organization - Create and navigate through folders for better file organization
• 🎯 Modal Interface - Clean modal popup for seamless integration into any application
• 📤 Drag & Drop Upload - Intuitive file uploading with progress indicators
• 🔍 Search & Filter - Search files by name and filter by type (image, video, pdf, etc.)
• 🎨 Customizable Theming - Customize colors and styling to match your brand
• 📱 Responsive Design - Works perfectly on desktop and mobile devices
• 🎬 Video Support - Preview videos with built-in player
• 📄 Multiple File Types - Support for images, videos, PDFs, and other file types
• ⚡ TypeScript Support - Full TypeScript support with comprehensive type definitions
• 🔄 Event Callbacks - Comprehensive event system for upload/delete success/error handling

Installation

npm install media-library-s3

or

yarn add media-library-s3

Quick Start

Basic Usage with Modal

import React from 'react';
import { MediaLibraryModal } from 'media-library-s3';

function App() {
  const backendUrl = 'https://your-backend-url.com';

  const getMediaList = async (folderPath?: string) => {
    const url = folderPath 
      ? `${backendUrl}/media?prefix=${encodeURIComponent(folderPath)}`
      : `${backendUrl}/media`;
    const response = await fetch(url);
    return response.json();
  };

  const getUploadUrl = async (file: File, folderPath?: string) => {
    const response = await fetch(`${backendUrl}/media/upload-url`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ 
        fileName: file.name, 
        fileType: file.type,
        folderPath: folderPath || ''
      }),
    });
    return response.json();
  };

  const deleteFile = async (key: string) => {
    await fetch(`${backendUrl}/media/${encodeURIComponent(key)}`, {
      method: 'DELETE',
    });
  };

  const createFolder = async (folderName: string, parentPath?: string) => {
    const response = await fetch(`${backendUrl}/media/folder`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ folderName, parentPath: parentPath || '' }),
    });
    return response.json();
  };

  const handleSelect = (files: any[]) => {
    console.log('Selected files:', files);
  };

  return (
    <div>
      <h1>My Application</h1>
      <MediaLibraryModal
        trigger={<button>Open Media Library</button>}
        getMediaList={getMediaList}
        getUploadUrl={getUploadUrl}
        deleteFile={deleteFile}
        createFolder={createFolder}
        onSelect={handleSelect}
        allowMultiple={true}
      />
    </div>
  );
}

Direct Component Usage

import React from 'react';
import { MediaLibrary } from 'media-library-s3';

function MediaPage() {
  // ... same API functions as above

  return (
    <div>
      <MediaLibrary
        getMediaList={getMediaList}
        getUploadUrl={getUploadUrl}
        deleteFile={deleteFile}
        createFolder={createFolder}
        onSelect={handleSelect}
        allowMultiple={true}
        theme={{
          primaryColor: '#007bff',
          backgroundColor: '#ffffff',
          textColor: '#333333',
        }}
      />
    </div>
  );
}

API Reference

MediaLibraryModal Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | trigger | React.ReactNode | ✅ | Element that triggers the modal (e.g., button) | | getMediaList | (folderPath?: string) => Promise<MediaFile[]> | ✅ | Function to fetch media files | | getUploadUrl | (file: File, folderPath?: string) => Promise<{uploadUrl: string, key: string}> | ✅ | Function to get upload URL | | deleteFile | (key: string) => Promise<void> | ✅ | Function to delete files | | onSelect | (files: MediaFile[]) => void | ✅ | Callback when files are selected | | createFolder | (folderName: string, parentPath?: string) => Promise<{key: string}> | ❌ | Function to create folders | | allowMultiple | boolean | ❌ | Allow multiple file selection | | theme | ThemeConfig | ❌ | Custom theme configuration | | onUploadSuccess | (file: MediaFile) => void | ❌ | Upload success callback | | onUploadError | (error: any) => void | ❌ | Upload error callback | | onDeleteSuccess | (key: string) => void | ❌ | Delete success callback | | onDeleteError | (error: any) => void | ❌ | Delete error callback | | onFolderChange | (folderPath: string) => void | ❌ | Folder navigation callback |

MediaFile Interface

interface MediaFile {
  key: string;           // S3 object key
  name: string;          // Display name
  url: string;           // Public URL
  type: 'image' | 'video' | 'pdf' | 'other' | 'folder';
  thumbnailUrl?: string; // Thumbnail URL (optional)
  isFolder: boolean;     // Whether this is a folder
  size?: number;         // File size in bytes
  lastModified?: Date;   // Last modified date
  caption?: string;      // File caption (optional)
  tags?: string[];       // File tags (optional)
  metadata?: Record<string, any>; // Additional metadata
}

Theme Configuration

interface ThemeConfig {
  primaryColor?: string;    // Primary button color
  secondaryColor?: string;  // Secondary elements color
  backgroundColor?: string; // Background color
  textColor?: string;       // Text color
}

Backend Integration

This library requires a backend that provides the following API endpoints:

GET /media

List files and folders in a directory.

Query Parameters:

• prefix (optional): Folder path to list

Response:

[
  {
    "key": "folder1/",
    "name": "folder1",
    "type": "folder",
    "isFolder": true,
    "size": 0,
    "lastModified": "2025-01-01T00:00:00Z"
  },
  {
    "key": "folder1/image.jpg",
    "name": "image.jpg",
    "url": "https://bucket.s3.region.amazonaws.com/folder1/image.jpg",
    "type": "image",
    "isFolder": false,
    "size": 1024000,
    "lastModified": "2025-01-01T00:00:00Z"
  }
]

POST /media/upload-url

Generate a signed upload URL.

Request Body:

{
  "fileName": "example.jpg",
  "fileType": "image/jpeg",
  "folderPath": "folder1/"
}

Response:

{
  "uploadUrl": "https://bucket.s3.amazonaws.com/...",
  "key": "folder1/1234567890_example.jpg"
}

POST /media/folder

Create a new folder.

Request Body:

{
  "folderName": "new-folder",
  "parentPath": "parent-folder/"
}

DELETE /media/:key

Delete a file or folder (with all contents).

Backend Example

We provide a complete Node.js/Express backend example in the media-library-s3-backend package that you can use as a starting point. It includes:

• S3 integration with AWS SDK
• Folder management
• File upload/delete operations
• CORS configuration
• TypeScript support

Styling

The library comes with default styling that works out of the box. You can customize the appearance using the theme prop or by overriding CSS classes.

Custom CSS Classes

The library uses these CSS classes that you can override:

• .media-library-container
• .media-grid
• .media-grid-item
• .upload-area
• .folder-navigation

Examples

With Custom Theme

<MediaLibraryModal
  trigger={<button>Select Media</button>}
  // ... other props
  theme={{
    primaryColor: '#28a745',
    backgroundColor: '#f8f9fa',
    textColor: '#495057',
  }}
/>

With Event Callbacks

<MediaLibraryModal
  trigger={<button>Manage Files</button>}
  // ... other props
  onUploadSuccess={(file) => {
    console.log('File uploaded:', file.name);
    // Show success notification
  }}
  onUploadError={(error) => {
    console.error('Upload failed:', error);
    // Show error notification
  }}
  onFolderChange={(path) => {
    console.log('Navigated to:', path);
    // Update breadcrumbs or URL
  }}
/>

TypeScript Support

This library is written in TypeScript and provides comprehensive type definitions. All components, props, and interfaces are fully typed.

Browser Support

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

Contributing

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

License

MIT © Your Name

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions