React Media Gallery

A modern, responsive media gallery component for React applications with support for images and videos.

Features

• Responsive grid and list view layouts
• Image and video support
• Interactive preview mode with keyboard navigation
• Thumbnail navigation for easy browsing
• Support for favorites, delete, info, and download actions
• Metadata panel with detailed information
• Fully customizable via props

Installation

npm install react-media-gallery

Basic Usage

import React from 'react';
import { MediaGallery } from 'react-media-gallery';
import 'react-media-gallery/dist/styles.css'; // Import the styles

// Sample media items
const mediaItems = [
  {
    id: 1,
    type: 'image',
    title: 'Mountain Landscape',
    description: 'Beautiful mountain landscape at sunset',
    thumbnailUrl: 'https://example.com/thumbnail1.jpg',
    fullUrl: 'https://example.com/image1.jpg',
    createdAt: '2023-05-15T10:30:00Z'
  },
  {
    id: 2,
    type: 'video',
    title: 'Ocean Waves',
    description: 'Relaxing video of ocean waves',
    thumbnailUrl: 'https://example.com/thumbnail2.jpg',
    fullUrl: 'https://example.com/video1.mp4',
    duration: '02:30',
    createdAt: '2023-05-16T14:45:00Z'
  }
];

function App() {
  const handleFavorite = (id) => {
    console.log(`Toggle favorite for item ${id}`);
  };

  const handleDelete = (id) => {
    console.log(`Delete item ${id}`);
  };

  const handleInfo = (id) => {
    console.log(`Showing info for ${id}`);
  };

  const handleDownload = (id) => {
    console.log(`Download item ${id}`);
  };
  
  // Array of favorited item IDs
  const favoriteItems = [1];

  return (
    <div className="app">
      <h1>Media Gallery</h1>
      <MediaGallery
        mediaItems={mediaItems}
        onFavorite={handleFavorite}
        onDelete={handleDelete}
        onInfo={handleInfo}
        onDownload={handleDownload}
        favoriteItems={favoriteItems}
        defaultViewType="grid" // or 'list'
        defaultMediaType="all" // or 'image', 'video'
      />
    </div>
  );
}

export default App;

Props

MediaGallery Component

| Prop | Type | Default | Description | |------|------|---------|-------------| | mediaItems | MediaItem[] | [] | Array of media items to display | | isLoading | boolean | false | Loading state of the gallery | | defaultViewType | 'grid' | 'list' | 'grid' | Initial view type | | defaultMediaType | 'all' | 'image' | 'video' | 'all' | Initial media type filter | | onFilterChange | (type: MediaType) => void | undefined | Callback when media type filter changes | | onFavorite | (id: string) => void | undefined | Callback when favorite is toggled | | onDelete | (id: string) => Promise | undefined | Callback when delete is clicked | | onRestore | (id: string) => Promise | undefined | Callback when restore is clicked | | onInfo | (id: string) => void | undefined | Callback when info is clicked | | onDownload | (id: string) => void | undefined | Callback when download is clicked | | onLoadMore | () => void | undefined | Callback to load more items when preview nears the end | | hasMore | boolean | false | Whether more items can be loaded for infinite preview navigation | | isLoadingMore | boolean | false | Whether more items are currently being loaded | | loadMoreThreshold | number | 2 | How close to the end to trigger onLoadMore in preview (items from end) | | favoriteItems | string[] | [] | Array of favorited item IDs | | selectedMedia | string[] | [] | Array of selected item IDs | | onSelectedMedia | (id: string, isSelected: boolean) => void | undefined | Callback when media selection changes | | showInfoToggle | boolean | true | Whether to show the info toggle button | | className | string | '' | Additional CSS class name | | buttonPositions | object | see below | Positions for action buttons |

MediaItem Type

interface MediaItem {
  id: number;
  type: 'image' | 'video';
  title: string;
  description?: string | null;
  thumbnailUrl: string;
  fullUrl: string;
  duration?: string | null;
  createdAt: string;
}

Advanced Usage

Infinite Loading in Preview

Enable infinite scrolling in the full-screen preview mode so users can navigate through all media without closing the preview:

import React, { useState } from 'react';
import { MediaGallery } from 'react-media-gallery';

function App() {
  const [mediaItems, setMediaItems] = useState([/* initial items */]);
  const [hasMore, setHasMore] = useState(true);
  const [isLoadingMore, setIsLoadingMore] = useState(false);

  const handleLoadMore = async () => {
    if (isLoadingMore) return;
    
    setIsLoadingMore(true);
    try {
      // Fetch more items from your API
      const newItems = await fetchMoreMedia();
      setMediaItems(prev => [...prev, ...newItems]);
      setHasMore(newItems.length > 0);
    } finally {
      setIsLoadingMore(false);
    }
  };

  return (
    <MediaGallery
      mediaItems={mediaItems}
      onLoadMore={handleLoadMore}
      hasMore={hasMore}
      isLoadingMore={isLoadingMore}
      loadMoreThreshold={2} // Trigger load when 2 items from the end
      // ... other props
    />
  );
}

Using Individual Components

You can also use the individual components to build custom layouts:

import { 
  GalleryGrid, 
  GalleryItem, 
  MediaPreviewModal 
} from 'react-media-gallery';

Customization

The gallery can be customized using CSS variables or by overriding the default styles.