Fotorama React

A modern, pure React image gallery component inspired by Fotorama, built from the ground up with React best practices, TypeScript support, and zero jQuery dependency.

🔗 Links

• Full Documentation
• Live Demo
• npm Package
• GitHub Repository
• Issue Tracker

Features

• Pure React - No jQuery dependency, built for modern React
• Responsive - Works perfectly on desktop and mobile
• Keyboard Navigation - Arrow keys, F for fullscreen, Esc to exit
• Touch Support - Swipe gestures for mobile devices
• Customizable - Easy styling with CSS classes
• Accessible - ARIA labels, alt text, keyboard navigation
• TypeScript - Full type safety with exported interfaces
• SSR Compatible - Works with Next.js, Gatsby, and other SSR frameworks
• Performance - Optimized rendering and memory management
• Tree Shakable - Import only what you need

Installation

# npm
npm install fotorama-react

# yarn
yarn add fotorama-react

# pnpm
pnpm add fotorama-react

Quick Start

import React from 'react';
import Fotorama from 'fotorama-react';
import 'fotorama-react/dist/index.css'; // or 'fotorama-react/css' for convenience

const images = [
  'https://example.com/image1.jpg',
  'https://example.com/image2.jpg',
  'https://example.com/image3.jpg'
];

function App() {
  return (
    <Fotorama
      items={images}
      width="100%"
      height={400}
      nav="thumbs"
      allowfullscreen
      loop
      autoplay={3000}
    />
  );
}

export default App;

Documentation

• Complete API Documentation - Detailed guide with examples
• Live Demo - Interactive examples
• Migration Guide - From jQuery Fotorama

Key Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | items ⭐ | Array<string \| FotoramaItem> | Required | Images to display | | width | number \| string | '100%' | Gallery width | | height | number \| string | 400 | Gallery height | | nav | 'dots' \| 'thumbs' \| false | 'dots' | Navigation style | | allowfullscreen | boolean \| 'native' | false | Enable fullscreen | | autoplay | boolean \| number | false | Auto-advance (ms) | | transition | 'slide' \| 'crossfade' | 'slide' | Animation type |

→ See all props in documentation

Image Formats

Simple URLs

const items = [
  'https://example.com/image1.jpg',
  'https://example.com/image2.jpg'
];

Rich Objects with Metadata

const items = [
  {
    img: 'https://example.com/full-image.jpg',
    thumb: 'https://example.com/thumbnail.jpg',
    alt: 'Beautiful landscape',
    caption: 'Shot with NIKON D850 • 24-70mm f/2.8',
    popup: 'https://example.com/high-res.jpg' // For fullscreen
  }
];

Imperative API

Control the gallery programmatically using refs:

import { useRef } from 'react';
import Fotorama, { FotoramaAPI } from 'fotorama-react';

function GalleryWithControls() {
  const galleryRef = useRef<FotoramaAPI>(null);

  const goToNext = () => galleryRef.current?.next();
  const goToPrev = () => galleryRef.current?.prev();
  const enterFullscreen = () => galleryRef.current?.fullscreen();

  return (
    <div>
      <Fotorama ref={galleryRef} items={images} />
      <button onClick={goToPrev}>← Previous</button>
      <button onClick={goToNext}>Next →</button>
      <button onClick={enterFullscreen}>🔍 Fullscreen</button>
    </div>
  );
}

Styling & Theming

/* Import the base styles */
@import 'fotorama-react/dist/index.css'; /* or 'fotorama-react/css' */

/* Customize the gallery */
.my-gallery {
  border-radius: 12px;
  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.3);
}

.my-gallery .react-fotorama__caption {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border-radius: 8px;
  backdrop-filter: blur(10px);
}

Framework Integration

Next.js

import dynamic from 'next/dynamic';

const Fotorama = dynamic(() => import('fotorama-react'), {
  ssr: false, // Optional: disable SSR
  loading: () => <div>Loading gallery...</div>
});

Gatsby

// Works out of the box with Gatsby
import Fotorama from 'fotorama-react';

Vite

// Works seamlessly with Vite
import Fotorama from 'fotorama-react';

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import Fotorama, { 
  FotoramaProps, 
  FotoramaAPI, 
  FotoramaItem 
} from 'fotorama-react';

// All props are typed
const props: FotoramaProps = {
  items: images,
  width: 800,
  height: 600,
  nav: 'thumbs'
};

// API methods are typed
const api: FotoramaAPI = galleryRef.current;

Compared to Alternatives

| Feature | React Fotorama | React Image Gallery | React Responsive Carousel | |---------|---------------|-------------------|-------------------------| | No jQuery | ✅ | ✅ | ✅ | | TypeScript | ✅ | ❌ | ❌ | | Touch/Swipe | ✅ | ✅ | ✅ | | Keyboard Nav | ✅ | ❌ | ❌ | | Fullscreen | ✅ | ✅ | ❌ | | Thumbnails | ✅ | ✅ | ❌ | | SSR Safe | ✅ | ❌ | ✅ | | Bundle Size | ~15KB | ~25KB | ~20KB |

Migration from jQuery Fotorama

Migrating is straightforward with similar API design:

// Before (jQuery)
$('.fotorama').fotorama({
  width: 700,
  nav: 'thumbs',
  allowfullscreen: true
});

// After (React)
<Fotorama
  width={700}
  nav="thumbs"
  allowfullscreen
  items={images}
/>

→ Complete migration guide

Contributing

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

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Reporting Issues

Found a bug or have a feature request? Please open an issue with:

• React version
• Browser and OS
• Steps to reproduce
• Expected vs actual behavior

License

MIT License - see LICENSE file for details.

This project is free and open source. You can use it for any purpose, including commercial projects.

Credits & Acknowledgments

• Inspired by Fotorama by Art Polikarpov (MIT License)
• Demo Photography by Vladimir Bolshakov
• Built with ❤️ by the React community

Note: This is a complete React rewrite and does not include any original Fotorama code. Both projects use the permissive MIT License.

⭐ Star us on GitHub if you find this project useful!

Made with ❤️ for the React community