react-masonry-virtualized

A high-performance, virtualized masonry grid component for React with dynamic column layout, lazy loading, and interactive 3D zoom effects.

Features

• 🚀 High Performance: Virtual scrolling renders only visible items
• 📱 Responsive: Automatically adjusts columns based on container width
• 🎨 Flexible: Works with any content type (images, cards, etc.)
• 💪 TypeScript: Full type safety and IntelliSense support
• ⚡ Optimized: Uses RAF, memoization, and CSS containment
• 🎯 Zero Dependencies: Only peer dependencies on React
• 📦 Lightweight: < 7KB minified
• ♾️ Infinite Scroll: Built-in onEndReached callback
• 🖥️ SSR Ready: Placeholder support for hydration
• 🦴 Skeleton Loading: Pixel-perfect skeleton cards auto-sized to actual column widths
• 🔍 Zoom-on-Hover: Hold Z + hover for 3D perspective tilt with dynamic shadows
• 🎯 Programmatic Scroll: Scroll to any item by index using scrollToIndex via ref
• 🪟 Custom Scroller: Drop-in support for OverlayScrollbars, SimpleBar, Lenis, and any custom scroll container

Installation

npm install react-masonry-virtualized

yarn add react-masonry-virtualized

pnpm add react-masonry-virtualized

Usage

Basic Example with Images

import { MasonryGrid, getImageSize } from 'react-masonry-virtualized';

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

function App() {
  return (
    <MasonryGrid
      items={images}
      renderItem={(src, index) => (
        <img
          src={src}
          alt={`Image ${index}`}
          loading="lazy"
          style={{ width: '100%', height: 'auto', display: 'block' }}
        />
      )}
      getItemSize={async (src) => await getImageSize(src)}
      gap={16}
      minWidth={280}
    />
  );
}

Infinite Scroll Example

import { MasonryGrid, getImageSize } from 'react-masonry-virtualized';

function App() {
  const [images, setImages] = useState(initialImages);
  const [loading, setLoading] = useState(false);

  const loadMore = async () => {
    if (loading) return;
    setLoading(true);
    const newImages = await fetchMoreImages();
    setImages(prev => [...prev, ...newImages]);
    setLoading(false);
  };

  return (
    <MasonryGrid
      items={images}
      renderItem={(src, index) => (
        <img src={src} alt={`Image ${index}`} loading="lazy" />
      )}
      getItemSize={async (src) => await getImageSize(src)}
      onEndReached={loadMore}
      onEndReachedThreshold={500}
    />
  );
}

Pre-computed Dimensions (Faster)

If you already know item dimensions, return them immediately for better performance:

<MasonryGrid
  items={posts}
  renderItem={(post) => <PostCard post={post} />}
  getItemSize={(post) => Promise.resolve({ 
    width: post.width, 
    height: post.height 
  })}
/>

SSR with Loading Placeholder

<MasonryGrid
  items={images}
  renderItem={(src) => <img src={src} />}
  getItemSize={async (src) => await getImageSize(src)}
  ssrPlaceholder={
    <div className="grid grid-cols-3 gap-4">
      {[...Array(9)].map((_, i) => (
        <div key={i} className="h-64 bg-gray-200 animate-pulse rounded" />
      ))}
    </div>
  }
/>

Loading Skeleton (Pixel-Perfect Alignment)

Pass a single card template via loadingPlaceholder and the library renders it in the exact same columns as the real grid — you get perfectly-aligned skeletons without duplicating any layout logic yourself.

function SkeletonCard() {
  return (
    <div
      style={{
        width: '100%',
        height: '100%',
        borderRadius: 16,
        background: 'linear-gradient(90deg, #e2e8f0 25%, #f1f5f9 50%, #e2e8f0 75%)',
        backgroundSize: '200% 100%',
        animation: 'shimmer 1.4s infinite',
      }}
    />
  );
}

function App() {
  const [pins, setPins] = useState([]);
  const [isLoading, setIsLoading] = useState(true);

  return (
    <MasonryGrid
      items={pins}
      renderItem={(pin) => <PinCard pin={pin} />}
      getItemSize={(pin) => Promise.resolve({ width: pin.w, height: pin.h })}
      // Library handles layout — skeletons match the real columns & widths
      loadingPlaceholder={<SkeletonCard />}
      skeletonCount={12}          // how many cards to show (default: 12)
      skeletonAspectRatio={1.3}   // card height / width ratio (default: 1.3)
    />
  );
}

Note: loadingPlaceholder is active while getItemSize is resolving. Once dimensions are loaded the real grid replaces it. For SSR hydration use ssrPlaceholder as before.

Zoom-on-Hover (3D Tilt)

Hold the Z key and hover over any card to zoom it with a 3D perspective tilt and dynamic shadow. Cards tilt toward your cursor with realistic depth.

<MasonryGrid
  items={images}
  renderItem={(src) => <img src={src} style={{ width: '100%', height: '100%', objectFit: 'cover' }} />}
  getItemSize={async (src) => await getImageSize(src)}
  enableZoomOnHover        // Enable the feature
  zoomScale={1.1}          // 10% larger on zoom (default: 1.08)
/>

How it works:

1. Press and hold Z → hover a card → card scales up with smooth animation
2. Move mouse → card tilts in 3D (±15°) with shadow shifting opposite to the tilt
3. Release Z or leave the card → instantly snaps back (no animation)
4. Must release and re-press Z for each zoom cycle — prevents accidental continuous zooming

Programmatic Scrolling

You can scroll to a specific item by index using the scrollToIndex method via a React ref.

import { useRef } from 'react';
import { MasonryGrid, MasonryGridRef } from 'react-masonry-virtualized';

function App() {
  const gridRef = useRef<MasonryGridRef>(null);

  const handleScroll = () => {
    // Scroll to item at index 50
    gridRef.current?.scrollToIndex(50, { 
      behavior: 'smooth', 
      offset: 20 
    });
  };

  return (
    <>
      <button onClick={handleScroll}>Scroll to 50</button>
      <MasonryGrid ref={gridRef} items={items} ... />
    </>
  );
}

Custom Scroll Container (OverlayScrollbars, SimpleBar, Lenis, …)

By default the grid listens for scroll events on window. Wrap the grid inside any custom scroller and pass its scrollable viewport element via scrollContainer to keep virtualization, infinite scroll, and scrollToIndex working correctly.

With OverlayScrollbars

import { useRef } from 'react';
import { useOverlayScrollbars } from 'overlayscrollbars-react';
import 'overlayscrollbars/overlayscrollbars.css';
import { MasonryGrid } from 'react-masonry-virtualized';

function App() {
  const containerRef = useRef<HTMLDivElement>(null);
  const [initialize, getInstance] = useOverlayScrollbars({
    options: { scrollbars: { autoHide: 'scroll' } },
  });

  // initialize OverlayScrollbars on the wrapper div
  useEffect(() => {
    if (containerRef.current) initialize(containerRef.current);
  }, [initialize]);

  // get the inner viewport element that actually scrolls
  const viewport = getInstance()?.elements().viewport;

  return (
    <div ref={containerRef} style={{ height: '100vh' }}>
      <MasonryGrid
        items={items}
        renderItem={(item) => <Card item={item} />}
        getItemSize={(item) => Promise.resolve({ width: item.w, height: item.h })}
        scrollContainer={viewport}
      />
    </div>
  );
}

With a plain scrollable div (or any other library)

import { useRef } from 'react';
import { MasonryGrid } from 'react-masonry-virtualized';

function App() {
  const scrollRef = useRef<HTMLDivElement>(null);

  return (
    <div
      ref={scrollRef}
      style={{ height: '100vh', overflowY: 'auto' }}
    >
      <MasonryGrid
        items={items}
        renderItem={(item) => <Card item={item} />}
        getItemSize={(item) => Promise.resolve({ width: item.w, height: item.h })}
        scrollContainer={scrollRef}   // pass the ref directly
      />
    </div>
  );
}

Note: The scroll container element must have overflow: auto or overflow-y: scroll and a fixed height. The MasonryGrid itself should not have a fixed height when using a custom container — let it grow naturally inside the scrollable parent.

Fixed Column Count

<MasonryGrid
  items={images}
  columnCount={4}  // Always 4 columns
  // ... other props
/>

API

MasonryGrid Props

Prop	Type	Default	Description
items	T[]	required	Array of items to render
renderItem	(item: T, index: number) => ReactNode	required	Function to render each item
getItemSize	(item: T, index: number) => Promise<{width, height}>	required	Function to get item dimensions
baseWidth	number	241	Base width for scaling calculations
minWidth	number	223	Minimum width for each column
gap	number	16	Gap between items in pixels
className	string	''	Container class name
style	CSSProperties	undefined	Container inline styles
bufferMultiplier	number	1	Viewport buffer (1 = 1 viewport above/below)
columnCount	number	undefined	Override auto column count
onEndReached	() => void	undefined	Callback when scrolled near end
onEndReachedThreshold	number	500	Distance from end to trigger callback (px)
ssrPlaceholder	ReactNode	undefined	Placeholder during SSR/hydration (before JS runs)
disableVirtualization	boolean	false	Render all items (disables virtual scroll)
loadingPlaceholder	ReactNode	undefined	Single card template tiled in masonry columns while loading
skeletonCount	number	12	Number of skeleton cards to render
skeletonAspectRatio	number	1.3	Height/width ratio used for skeleton card sizing
enableZoomOnHover	boolean	false	Hold Z key + hover to zoom & 3D-tilt cards
zoomScale	number	1.08	Scale multiplier when zoom is active (e.g. 1.1 = 10% larger)
scrollContainer	HTMLElement | RefObject<HTMLElement> | null	undefined	Custom scroll container — pass an element or ref when using OverlayScrollbars, SimpleBar, Lenis, etc.
ref	Ref<MasonryGridRef>	undefined	Ref to access imperative methods

MasonryGridRef Methods

Method	Arguments	Description
scrollToIndex	(index: number, options?: { behavior: 'smooth' | 'auto', offset: number })	Scrolls the grid to the item at the specified index.

Helper Functions

getImageSize(src: string): Promise<{width, height}>

Helper function to load image dimensions. Useful for image-based masonry grids.

import { getImageSize } from 'react-masonry-virtualized';

const dimensions = await getImageSize('https://example.com/image.jpg');
// { width: 1920, height: 1080 }

How It Works

1. Dynamic Columns: Calculates optimal number of columns based on container width and minWidth
2. Masonry Layout: Places items in the shortest column (Pinterest-style)
3. Virtual Scrolling: Only renders items visible in viewport + buffer
4. Performance Optimization:
   • React.memo prevents unnecessary re-renders
   • useCallback memoizes expensive calculations
   • requestAnimationFrame throttles scroll events
   • Debounced resize handler
   • CSS containment for layout isolation
   • GPU-accelerated transforms with translate3d

Performance Tips

1. Memoize getItemSize: If dimensions don't change, cache them
2. Use pre-computed dimensions: Return Promise.resolve() for known sizes
3. Adjust bufferMultiplier: Lower values render fewer items (faster) but may show blank space while scrolling
4. Use loading="lazy": For images, enable native lazy loading
5. Optimize images: Use appropriately sized images

Performance Benchmarks

Benchmarked with 500 items, scrolling 5000px down and back up. Measured on Chrome.

Library	Avg FPS	Min FPS	Memory
🏆 react-masonry-virtualized	60	59	54 MB
masonic	60	57	48 MB
react-virtualized	60	54	70 MB
@tanstack/react-virtual	59	56	49 MB

Bundle size: 6.5 KB minified · 2 KB gzipped · Zero dependencies

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.

Credits

Built with ❤️ using React, TypeScript, and tsup.