react-advanced-gallery/README.md

A customizable React image gallery component with Bootstrap styling, fullscreen mode, animations, and support for various media types

# React Advanced Gallery

A fully customizable React image gallery component with advanced features, inspired by LightGallery but with extended functionality and a modern design.

## Features

### Core Features
- Thumbnail navigation
- Fullscreen mode
- Zoom in/out capabilities
- Multiple transition animations (fade, slide, zoom)
- Keyboard, mouse, and touch navigation
- Lazy loading and image preloading
- Multiple layout options (grid, masonry, carousel)
- Light/dark mode support

### Image Features
- Support for images, videos, and external links
- Caption and metadata display (title, description, EXIF data)
- Favorite/star functionality
- Image removal capability
- File upload support

### Customization
- Built-in Bootstrap-compatible styling
- Customizable layouts and animations
- Extensible with hooks for various events (click, slide change, etc.)
- Custom icon support
- Easily override styles with your own CSS

## Installation

```bash
npm install react-advanced-gallery
# or
yarn add react-advanced-gallery
```

## Basic Usage

```jsx
import { ImageGallery } from 'react-advanced-gallery';
import 'react-advanced-gallery/dist/styles.css';

const images = [
  {
    id: '1',
    src: 'https://example.com/image1.jpg',
    thumbnail: 'https://example.com/thumbnail1.jpg',
    alt: 'Description of image 1',
    title: 'Image 1 Title',
    description: 'This is the first image',
    type: 'image',
    isFavorite: false
  },
  // More images...
];

function App() {
  return (
    <div className="App">
      <ImageGallery 
        images={images}
        layout="grid"
        animation="fade"
      />
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `images` | `GalleryItem[]` | Required | Array of image objects |
| `layout` | `'grid' \| 'masonry' \| 'carousel'` | `'grid'` | Layout style for the gallery |
| `animation` | `'fade' \| 'slide' \| 'zoom' \| 'none'` | `'fade'` | Animation type for transitions |
| `thumbnailsPosition` | `'bottom' \| 'top' \| 'left' \| 'right'` | `'bottom'` | Position of thumbnails in fullscreen mode |
| `enableZoom` | `boolean` | `true` | Enable zoom functionality |
| `darkMode` | `boolean` | `false` | Force dark mode (otherwise follows system/theme) |
| `onImageClick` | `(image: GalleryItem) => void` | - | Callback when an image is clicked |
| `onFavoriteToggle` | `(image: GalleryItem) => void` | - | Callback when favorite status is toggled |
| `onImageRemove` | `(image: GalleryItem) => void` | - | Callback when an image is removed |
| `onImageUpload` | `(files: File[]) => void` | - | Callback when files are uploaded |

## Image Object Structure

```typescript
interface GalleryItem {
  id: string;
  src: string;
  thumbnail: string;
  alt: string;
  title: string;
  description: string;
  metadata?: {
    camera?: string;
    lens?: string;
    aperture?: string;
    shutterSpeed?: string;
    iso?: string;
    focalLength?: string;
    dateTaken?: string;
    fileSize?: string;
    dimensions?: string;
  };
  type: 'image' | 'video' | 'external';
  isFavorite: boolean;
}
```

## License

MIT