react-plock

By default, the masonry layout distributes items sequentially. To create a more visually harmonious grid that minimizes height differences between columns, set useBalancedLayout: true in the config object. This is ideal for content with varying heights like images or cards.

<Masonry
  items={items}
  config={{
    columns: [2, 3, 4],
    gap: [16, 16, 16],
    media: [640, 768, 1024],
    useBalancedLayout: true, // Enable balanced layout
  }}
  render={(item) => (
    <img src={item.url} alt={item.alt} style={{ width: '100%' }} />
  )}
/>

To start the development server for this Next.js example project, use your preferred package manager to run the dev script. Once running, you can view the application at http://localhost:3000.

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

To use React Plock in your project, install the package using npm:

npm install react-plock

The Masonry component uses two different strategies to distribute items into columns:

1. Chunked Layout (Default): Uses createChunks and createDataColumns. Items are grouped into rows of a specific size and then distributed into columns. This is faster but can result in uneven column heights if items have varying heights.
2. Balanced Layout: Triggered by setting useBalancedLayout: true in the config. It uses createBalancedColumns to track the height of each item (via getBoundingClientRect) and assigns the next item to the currently shortest column. This results in much more even column heights but requires an extra render pass to measure heights.

When providing arrays for columns or gap to create a responsive layout, the number of elements in those arrays MUST be equal to the number of elements in the media array. Failing to match these lengths will cause rendering issues.

// Correct: 3 breakpoints
<Masonry
  config={{
    columns: [1, 2, 3],
    gap: [12, 16, 20],
    media: [640, 768, 1024],
  }}
/>

// Correct: Fixed columns (no media array needed)
<Masonry
  config={{
    columns: 4,
    gap: 8
  }}
/>

// NOT Correct: Mismatched array lengths
<Masonry
  config={{
    columns: [4],
    media: [640, 768],
  }}
/>

Use the Masonry component to render a responsive masonry layout. You provide an array of items, a config object for layout rules, and a render function to define how each item is displayed.

import { Masonry } from 'react-plock';

const ImagesMasonry = () => {
  const items = [...imageUrls];

  return (
    <Masonry
      items={items}
      config={{
        columns: [1, 2, 3],
        gap: [24, 12, 6],
        media: [640, 768, 1024],
      }}
      render={(item, idx) => (
        <img key={idx} src={item} style={{ width: '100%', height: 'auto' }} />
      )}
    />
  );
};

The config object controls the responsiveness and spacing of the grid:

• columns: A single number for a fixed column count, or an array of numbers for responsive breakpoints.
• gap: A single number for a fixed gap, or an array of numbers for responsive breakpoints.
• media?: An array of numbers representing media query breakpoints. If columns or gap are arrays, the length of media must match the number of breakpoints provided.

The createBalancedColumns utility distributes items into a specified number of columns by always picking the shortest column to place the next item. This requires a getHeight callback to determine the height of each item.

Signature: createBalancedColumns<T>(items: T[], columns: number, getHeight: (item: T) => number): T[][]

const columns = createBalancedColumns(
  items, 
  3, 
  (item) => item.height
);

The MasonryRow component is a sub-component used to render a single column of items within the masonry grid. It uses a CSS grid with rowGap to manage spacing between items in that specific column.

<MasonryRow gap={16}>
  <div>Item 1</div>
  <div>Item 2</div>
</MasonryRow>