Lazy Image Gallery

View in Storybook

Explore interactive examples and all component variations in our Storybook.

The LazyImageGallery component provides an efficient way to display large collections of images with lazy loading. Built with Intersection Observer API, it only loads images when they come into view, improving performance and reducing bandwidth usage. Perfect for photo galleries, product catalogs, portfolios, and any interface displaying multiple images.

Basic Usage

View in Storybook

Custom Grid Layout

Portfolio Gallery

Photography Portfolio

Product Catalog

Product Catalog

Showing 8 products • Scroll to see more

Large Image Collection

Large Collection (50 images)

💡 This gallery demonstrates lazy loading with 50 images. Images are only loaded when they come into view, improving performance.

Properties

LazyImageGallery

Property	Type	Description
images	string[]	Array of image URLs to display in the gallery.
observerOptions	IntersectionObserverInit	Configuration options for the Intersection Observer.
classNames	GalleryClassNames	Custom CSS classes for styling different parts of the gallery.

GalleryClassNames

Property	Type	Description
imageGallery	string	CSS classes for the main gallery container.
imageCell	string	CSS classes for individual image containers.
image	string	CSS classes for the image elements.

IntersectionObserverInit (observerOptions)

Property	Type	Default	Description
root	Element | null	null	The element used as the viewport for checking visibility.
rootMargin	string	"0px"	Margin around the root. Can be used to load images before they're visible.
threshold	number | number[]	1	Percentage of target visibility that triggers the observer.

Default Styling

The component comes with default responsive grid styling:

.image-gallery {
  overflow: auto;
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: 0.5rem;
  justify-content: center;
  height: 100%;
}

.image-cell {
  width: 100%;
  height: 13rem; /* 208px */
}

.image {
  width: 100%;
  height: 100%;
  object-fit: cover;
  animation: fade-up 400ms ease-linear;
}

Performance Features

Lazy Loading Benefits

• Reduced Initial Load Time - Only loads visible images
• Bandwidth Savings - Saves data by not loading off-screen images
• Memory Efficiency - Reduces memory usage for large galleries
• Smooth Scrolling - Maintains smooth scroll performance

Intersection Observer

• Native Browser API - Uses efficient browser-native intersection detection
• Configurable Thresholds - Control when images start loading
• Root Margin - Pre-load images before they become visible
• Automatic Cleanup - Properly disconnects observers on unmount

Accessibility

The LazyImageGallery component includes basic accessibility features:

• Alt Text - Automatically generates descriptive alt text for images
• Keyboard Navigation - Images can be focused and navigated with keyboard
• Screen Reader Support - Proper image semantics for assistive technologies
• Loading States - Clear indication when images are loading
• Error Handling - Graceful handling of failed image loads

Common Use Cases

The LazyImageGallery component is perfect for:

• Photo Galleries - Personal or professional photography showcases
• Product Catalogs - E-commerce product image displays
• Portfolio Websites - Creative work and project showcases
• Social Media Feeds - Image-heavy social content
• Real Estate Listings - Property photo galleries
• Art Collections - Museum or gallery image collections
• Travel Websites - Destination and attraction photos
• News Articles - Image galleries in editorial content

Best Practices

1. Image Optimization - Use appropriately sized images for your layout
2. Consistent Aspect Ratios - Maintain consistent image dimensions when possible
3. Loading Indicators - Consider adding loading skeletons or placeholders
4. Error Handling - Implement fallback images for failed loads
5. Performance Monitoring - Monitor loading performance with large galleries
6. Mobile Optimization - Test gallery performance on mobile devices
7. Accessibility - Provide meaningful alt text for all images
8. SEO Considerations - Use descriptive filenames and proper image metadata

Performance Tips

1. Root Margin - Use rootMargin to pre-load images just before they're needed
2. Image Formats - Use modern formats like WebP for better compression
3. CDN Usage - Serve images from a CDN for faster loading
4. Responsive Images - Use different image sizes for different screen sizes
5. Batch Loading - Consider loading images in small batches rather than one by one
6. Memory Management - For very large galleries, consider unloading off-screen images