React Native Overlap Gallery

A performant React Native gallery component featuring overlapping circular cards with beautiful scroll effects. Perfect for showcasing images in a unique, eye-catching way with smooth animations, parallax effects, and detail views.

🎥 Video Demo

📹 Watch Demo Video

Note: For better browser compatibility and inline playback on GitHub, consider converting the .mov file to .mp4 format. You can use tools like FFmpeg or online converters.

Features

✨ Vertical scrollable gallery - Beautiful overlapping circular cards in a vertical list
🎬 Smooth scroll effects - Fade-in, scale, and parallax animations as you scroll
⚡ Optimized performance - Efficient rendering with React Native Animated API
🎯 Click to view details - Modal with detailed view and custom border radius
🎨 Customizable - Adjust card size, overlap offset, and positioning
📱 TypeScript support - Fully typed for better developer experience
🔧 Flexible rendering - Custom detail content renderer support
🌊 Organic clustering - Cards naturally overlap and cluster for visual appeal

Installation

npm install react-native-overlap-gallery
# or
yarn add react-native-overlap-gallery

Peer Dependencies

Make sure you have these installed:

npm install react-native
# or
yarn add react-native

Usage

Basic Example

import React from "react";
import { SafeAreaView } from "react-native";
import { OverlapGallery, GalleryItem } from "react-native-overlap-gallery";

const data: GalleryItem[] = [
  {
    id: 1,
    image: "https://example.com/image1.jpg",
    title: "Image 1",
    description: "Description for image 1",
  },
  {
    id: 2,
    image: "https://example.com/image2.jpg",
    title: "Image 2",
    description: "Description for image 2",
  },
  // Add more items...
];

const App = () => {
  return (
    <SafeAreaView style={{ flex: 1 }}>
      <OverlapGallery data={data} />
    </SafeAreaView>
  );
};

export default App;

Customizing Card Size and Overlap

Adjust the card size and overlap to match your design:

import React from "react";
import { SafeAreaView } from "react-native";
import { OverlapGallery, GalleryItem } from "react-native-overlap-gallery";

const App = () => {
  return (
    <SafeAreaView style={{ flex: 1 }}>
      <OverlapGallery
        data={data}
        cardSize={180}      // Larger cards
        overlapOffset={50}  // More overlap
      />
    </SafeAreaView>
  );
};

export default App;

Advanced Usage with Custom Detail Content

import React from "react";
import { SafeAreaView, View, Text, StyleSheet } from "react-native";
import { OverlapGallery, GalleryItem } from "react-native-overlap-gallery";

const App = () => {
  const handleCardPress = (item: GalleryItem) => {
    console.log("Card pressed:", item.title);
  };

  const renderDetailContent = (item: GalleryItem) => (
    <View style={styles.customDetail}>
      <Text style={styles.title}>{item.title}</Text>
      <Text style={styles.description}>{item.description}</Text>
    </View>
  );

  return (
    <SafeAreaView style={{ flex: 1 }}>
      <OverlapGallery
        data={data}
        cardSize={150}
        overlapOffset={50}
        onCardPress={handleCardPress}
        renderDetailContent={renderDetailContent}
      />
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  customDetail: {
    padding: 20,
  },
  title: {
    fontSize: 24,
    fontWeight: "bold",
    marginBottom: 10,
  },
  description: {
    fontSize: 16,
    color: "#666",
  },
});

API Reference

OverlapGallery Props

| Prop | Type | Default | Description | | --------------------- | ------------------------------------- | ------------ | ----------------------------------------------- | | data | GalleryItem[] | Required | Array of gallery items to display | | cardSize | number | 150 | Size of the circular cards (width and height) | | overlapOffset | number | 30 | How much cards overlap each other | | onCardPress | (item: GalleryItem) => void | undefined | Callback when a card is pressed | | renderDetailContent | (item: GalleryItem) => ReactElement | undefined | Custom renderer for detail modal content |

GalleryItem Type

interface GalleryItem {
  id: string | number;
  image: string | { uri: string };
  title?: string;
  description?: string;
}

DetailModal Props

| Prop | Type | Default | Description | | --------------- | ------------------------------------- | ------------ | ----------------------------- | | visible | boolean | Required | Controls modal visibility | | item | GalleryItem \| null | Required | The item to display in detail | | onClose | () => void | Required | Callback when modal is closed | | renderContent | (item: GalleryItem) => ReactElement | undefined | Custom content renderer |

Scroll Effects

The gallery includes beautiful scroll animations:

• Fade-in Animation: Cards fade in with a staggered delay when first loaded
• Scale Animation: Cards spring into view with a smooth scale effect
• Parallax Scrolling: Cards fade and scale based on scroll position
• Vertical Parallax: Subtle vertical movement creates depth

All animations are optimized using React Native's Animated API with native driver for 60fps performance.

Styling

The component comes with default styling, but you can customize the appearance by:

1. Adjusting cardSize and overlapOffset props
2. Using renderDetailContent to customize the detail view
3. The detail view image automatically has a border radius of 5
4. Cards are positioned with organic clustering for natural overlap

Performance

This component is optimized for performance:

• Uses React Native's Animated API with native driver for smooth 60fps animations
• Efficient scroll event handling with throttling
• Optimized rendering with absolute positioning
• Minimal re-renders during scrolling

Examples

Check out the example-expo/ directory for a complete working example with all features demonstrated.

Requirements

• React Native >= 0.60.0
• React >= 16.8.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Author

Ashraz Rashid

Support

If you like this project, please consider giving it a ⭐️ on GitHub!