React Masonify

A lightweight React component library for creating responsive Masonry layouts.

Installation

npm install react-masonify
# or
yarn add react-masonify

Features

• 🎯 Responsive grid layouts
• 🪶 Lightweight implementation
• ⚡ Performance optimized
• 🔄 Dynamic column redistribution
• 📱 Breakpoint-based responsiveness
• 🎨 Customizable gaps and styling

Components

ResponsiveMasonry

A wrapper component that handles responsive behavior based on screen width breakpoints.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | columnsCountBreakPoints | { [key: number]: number } | { 350: 1, 750: 2, 900: 3 } | Object defining breakpoints and their corresponding column counts | | children | React.ReactNode | Required | Should be a Masonry component | | className | string \| null | null | Optional CSS class name | | style | CSSProperties \| null | null | Optional inline styles |

Masonry

The core component that creates the masonry layout.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | React.ReactNode | Required | Items to be arranged in the masonry layout | | columnsCount | number | 3 | Number of columns (automatically set when used with ResponsiveMasonry) | | gap | string | "0" | Gap between items (CSS value) | | className | string \| null | null | Optional CSS class name | | style | React.CSSProperties | {} | Optional inline styles | | containerTag | keyof JSX.IntrinsicElements | "div" | HTML tag for the container element | | itemTag | keyof JSX.IntrinsicElements | "div" | HTML tag for the items | | itemStyle | React.CSSProperties | {} | Styles applied to each item container | | sequential | boolean | false | If true, items are arranged sequentially instead of by height |

Basic Usage

import { Masonry, ResponsiveMasonry } from 'react-masonify';

const Gallery = () => {
  return (
    <ResponsiveMasonry
      columnsCountBreakPoints={{ 350: 1, 750: 2, 900: 3 }}
    >
      <Masonry gap="1rem">
        {images.map((src) => (
          <img src={src} key={src} alt="" />
        ))}
      </Masonry>
    </ResponsiveMasonry>
  );
};

Advanced Usage

Custom Breakpoints

const CustomGallery = () => {
  return (
    <ResponsiveMasonry
      columnsCountBreakPoints={{
        320: 1,  // 1 column for viewport width >= 320px
        480: 2,  // 2 columns for viewport width >= 480px
        720: 3,  // 3 columns for viewport width >= 720px
        1024: 4, // 4 columns for viewport width >= 1024px
      }}
    >
      <Masonry gap="1.5rem" itemTag="section">
        {items.map((item) => (
          <div key={item.id}>
            {/* Your content */}
          </div>
        ))}
      </Masonry>
    </ResponsiveMasonry>
  );
};

Custom Styling

const StyledGallery = () => {
  return (
    <ResponsiveMasonry
      style={{ padding: '20px' }}
      className="gallery-container"
    >
      <Masonry
        gap="2rem"
        itemStyle={{
          backgroundColor: '#f5f5f5',
          borderRadius: '8px',
          padding: '10px'
        }}
        style={{
          maxWidth: '1200px',
          margin: '0 auto'
        }}
      >
        {items.map((item) => (
          <div key={item.id}>
            {/* Your content */}
          </div>
        ))}
      </Masonry>
    </ResponsiveMasonry>
  );
};

How It Works

1. ResponsiveMasonry monitors the window width and determines the appropriate number of columns based on the provided breakpoints.

2. Masonry distributes children across columns using one of two strategies:

   • Default (sequential=false): Distributes items based on their heights to maintain balanced columns
   • Sequential (sequential=true): Distributes items sequentially from left to right

3. The layout automatically updates when:

   • The window is resized
   • Children are added or removed
   • The columns count changes

Browser Support

React Masonify works in all modern browsers that support CSS Flexbox:

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

TypeScript Support

React Masonify is written in TypeScript and includes built-in type definitions.

Performance Considerations

• Use the key prop with unique values for each child to ensure proper updates
• Avoid frequent changes to columnsCount or gap props
• Consider using sequential={true} for simpler layouts or when performance is crucial
• Use appropriate image sizes to prevent layout shifts

License

MIT License