Interactive Image Gallery

Installation

Usage

import InteractiveImageGallery from "@/components/ruixen/interactive-image-gallery";
 
export default function App() {
  const images = [
    {
      src: "/gallery/image1.jpg",
      alt: "Beautiful landscape",
      title: "Mountain Vista",
      description: "Stunning mountain view at sunset",
    },
    {
      src: "/gallery/image2.jpg",
      alt: "Ocean waves",
      title: "Ocean Serenity",
      description: "Peaceful ocean waves",
    },
    {
      src: "/gallery/image3.jpg",
      alt: "City lights",
      title: "Urban Nights",
      description: "City skyline at night",
    },
  ];
 
  return <InteractiveImageGallery images={images} />;
}

Props

InteractiveImageGallery Props

GalleryItem Props

Features

• Responsive Grid: Auto-adjusting columns based on screen size
• Hover Effects: Scale and overlay animations on hover
• Expandable View: Click to view full-size images
• Smooth Animations: Framer Motion powered transitions
• Keyboard Navigation: Arrow keys to navigate expanded view
• Touch Support: Swipe gestures on mobile devices
• Image Optimization: Next.js Image component integration
• Dark Mode: Adapts to theme automatically

Animation Details

Grid Item Hover

• Scale: 5% size increase (scale: 1.05)
• Overlay: Dark overlay fades in
• Text: Title and description slide up
• Duration: 0.3 seconds
• Easing: Smooth ease-out

Expanded View

• Backdrop: Animated dark overlay
• Image: Fade in with scale animation
• Navigation: Slide in from sides
• Exit: Smooth fade out
• Spring Physics: Natural motion

Customization

Custom Grid Columns

// 2 columns
<InteractiveImageGallery images={images} columns={2} />
 
// 4 columns
<InteractiveImageGallery images={images} columns={4} />
 
// Responsive (default)
<InteractiveImageGallery images={images} />

Custom Image Sizes

const images = [
  {
    src: "/large-image.jpg",
    alt: "Large format",
    title: "Featured Work",
    description: "High resolution showcase",
  },
];

Without Descriptions

const images = [
  {
    src: "/image.jpg",
    alt: "Simple image",
    title: "Title Only",
    // No description
  },
];

Styling

Grid Layout

• Mobile: 1 column
• Tablet: 2 columns (sm breakpoint)
• Desktop: 3 columns (md breakpoint)
• Large: Custom columns prop

Card Styling

• Aspect Ratio: 4:3 for consistent layout
• Border Radius: Rounded corners
• Shadow: Subtle elevation
• Overflow: Hidden for clean edges

Overlay

• Background: Black with 60% opacity
• Gradient: Bottom fade for text
• Padding: Generous spacing
• Text Color: White for contrast

Expanded View Features

Navigation

• Previous/Next Buttons: Arrow buttons on sides
• Keyboard: Left/Right arrow keys
• Touch: Swipe gestures
• Close: Click outside or ESC key

Image Display

• Max Size: Contained within viewport
• Aspect Ratio: Preserved
• Centering: Centered in viewport
• Loading: Smooth fade-in

Use Cases

• Portfolio Sites: Showcase creative work
• Photography: Display photo collections
• Product Galleries: Show product images
• Real Estate: Property photo galleries
• Art Exhibitions: Digital art displays
• Travel Blogs: Destination photo albums

Examples

Photography Portfolio

const photos = [
  {
    src: "/photos/landscape1.jpg",
    alt: "Mountain landscape",
    title: "Alpine Majesty",
    description: "Swiss Alps at golden hour",
  },
  {
    src: "/photos/portrait1.jpg",
    alt: "Portrait photography",
    title: "Urban Portrait",
    description: "Street photography series",
  },
];
 
<InteractiveImageGallery images={photos} columns={3} />;

Product Showcase

const products = [
  {
    src: "/products/shoe1.jpg",
    alt: "Running shoe",
    title: "Performance Runner",
    description: "Lightweight design for speed",
  },
  {
    src: "/products/shoe2.jpg",
    alt: "Training shoe",
    title: "All-Day Comfort",
    description: "Perfect for any workout",
  },
];
 
<InteractiveImageGallery images={products} columns={2} />;

Art Gallery

const artworks = [
  {
    src: "/art/painting1.jpg",
    alt: "Abstract painting",
    title: "Cosmic Dreams",
    description: "Acrylic on canvas, 2024",
  },
  {
    src: "/art/sculpture1.jpg",
    alt: "Modern sculpture",
    title: "Fluid Forms",
    description: "Bronze, limited edition",
  },
];
 
<InteractiveImageGallery images={artworks} columns={4} />;

Performance

• Lazy Loading: Images load as needed
• Optimized Images: Next.js automatic optimization
• Hardware Acceleration: Transform-based animations
• Efficient Rendering: Only visible items rendered
• Memory Management: Proper cleanup on unmount

Accessibility

• Keyboard Navigation: Full keyboard support
• Screen Readers: Descriptive alt text
• Focus Management: Proper focus handling
• ARIA Labels: Accessible button labels
• Color Contrast: High contrast text
• Focus Indicators: Clear focus states
• ESC to Close: Standard close behavior