react-layout-masonry

React Layout Masonry

React Layout Masonry is a flexible and customizable React component for creating dynamic and fixed/responsive masonry layouts.

Installation

You can install React Layout Masonry using npm, pnpm or yarn:

npm install react-layout-masonry

or

pnpm install react-layout-masonry

or

yarn add react-layout-masonry

Usage

Fixed Columns Layout

Here's an example of how to use React Layout Masonry with a fixed number of columns in your React application:

import Masonry from 'react-layout-masonry';

const FixedColumnsMasonry = () => {
  return (
    <Masonry
      columns={3}
      gap={16}
    >
      {items.map((item) => {
        return <Item {...item} />;
      })}
    </Masonry>
  );
};

export default FixedColumnsMasonry;

Responsive Columns Layout

Here's an example of how to use React Layout Masonry with responsive columns in your React application:

import Masonry from 'react-layout-masonry';

const ResponsiveColumnsMasonry = () => {
  return (
    <Masonry
      columns={{ 640: 1, 768: 2, 1024: 3, 1280: 5 }}
      gap={16}
    >
      {items.map((item) => {
        return <Item {...item} />;
      })}
    </Masonry>
  );
};

export default ResponsiveColumnsMasonry;

or use the array syntax

<Masonry columns={[1, undefined, undefined, 3]} />

this will be converted to

{
  "640": 1,
  "1280": 3
}

The array's order corresponds to the default breakpoints, which are 640, 786, 1024, 1280, 1536.

Column Props

The columnProps prop allows you to apply additional props to the container of each column. Here's an example:

<Masonry
  columns={3}
  gap={16}
  columnProps={{
    className: 'custom-column',
    style: { backgroundColor: 'lightgray' },
  }}
>
  {/* ... */}
</Masonry>

Props

• columns (number or object, required): The number of columns in the masonry layout, or an object with breakpoints and corresponding column counts.
• gap (number, optional): The spacing between columns and rows in pixels. Defaults to 0.
• columnProps (object, optional): Additional props to be applied to each column, such as className for styling.

Examples

For examples, usage and customization options, please refer to the docs directory in this repository.

Contributing

If you encounter any issues or have questions, please open an issue on our GitHub repository. Make sure to create an issue or discussion first before raising a PR

License

React Layout Masonry is open-source software licensed under the MIT License.

Changelog

v2.0.0 (2025-07-06)

Breaking Changes

Changed breakpoint matching logic from > to >=. When window width exactly matches a breakpoint value, that breakpoint is now active instead of the previous one. This aligns with standard CSS media query behavior where min-width: 768px activates at exactly 768px. (c4b4cbb)

[!NOTE] If you rely on the previous behavior where a window width of exactly 768px would use the 640px breakpoint configuration, you may need to adjust your breakpoint values accordingly.

Bug Fixes

• fix rendering in nextjs server components (dd30824)