pintrest-view

A Pinterest-style grid layout component for React.js with responsive design and dynamic content support. Create beautiful, responsive grid layouts that automatically adjust to your content.

Features

• 🎯 Simple API with minimal configuration required
• 📱 Responsive design with flexible column widths (pixels or percentages)
• 🌐 RTL (Right-to-Left) support for international layouts
• ↔️ Both vertical and horizontal layout options
• 🖼️ Automatic image handling with layout adjustments
• 🎨 Works with any React component
• 🚀 Optimized performance with minimal DOM operations
• 🖥️ Server-side rendering support
• 🔄 Smooth transitions during layout changes
• 🏎️ Virtualized Rendering – render only visible items for large grids to improve performance

Installation

# Using npm
npm install @zapperwing/pintrest-view

# Using yarn
yarn add @zapperwing/pintrest-view

Make sure you have react and react-dom installed in your project (version 17.0.0 or higher).

Quick Start

Here's a simple example to get you started:

import React from "react";
import StackGrid from "@zapperwing/pintrest-view";

const SimpleGrid = () => {
  return (
    <StackGrid 
      columnWidth={300}
      gutterWidth={15} 
      gutterHeight={15}
      virtualized={true}  // Enable virtualization for performance with many items
    >
      <div key="item1">First Item</div>
      <div key="item2">Second Item</div>
      <div key="item3">Third Item</div>
    </StackGrid>
  );
};

export default SimpleGrid;

Using Custom Components

The grid can handle any React component as a child. The only requirement is that each child must have a unique key prop:

import React from "react";
import StackGrid from "@zapperwing/pintrest-view";
import YourCustomCard from "./YourCustomCard";

const GridWithCustomComponents = () => {
  const items = [
    { id: 1, title: "First Card", content: "Some content..." },
    { id: 2, title: "Second Card", content: "More content..." },
    // ... more items
  ];

  return (
    <StackGrid 
      columnWidth={300}
      gutterWidth={15} 
      gutterHeight={15}
      monitorImagesLoaded={true} // Important if your components contain images
      virtualized={true}         // Activate virtualization for large grids
    >
      {items.map(item => (
        <YourCustomCard
          key={item.id.toString()} // Unique key is required
          title={item.title}
          content={item.content}
        />
      ))}
    </StackGrid>
  );
};

export default GridWithCustomComponents;

Tips for Custom Components

1. Height Calculation: The grid automatically detects the rendered height of your components. No special configuration is needed.
2. Images: If your components contain images, set monitorImagesLoaded={true} to ensure proper layout after images load.
3. Dynamic Content: If your component's height might change (e.g., expandable cards), call updateLayout() after the change:

const ExpandableCard = ({ content, gridRef }) => {
  const [isExpanded, setIsExpanded] = useState(false);

  const handleToggle = () => {
    setIsExpanded(!isExpanded);
    // Update grid layout after expansion/collapse
    if (gridRef.current) {
      gridRef.current.updateLayout();
    }
  };

  return (
    <div>
      <h3>Card Title</h3>
      {isExpanded ? <p>{content}</p> : null}
      <button onClick={handleToggle}>
        {isExpanded ? 'Show Less' : 'Show More'}
      </button>
    </div>
  );
};

Props

License

MIT

Changelog

1.0.0 (2024-03-11)

Breaking Changes

• Complete modernization of the codebase
• Removed animation system in favor of simpler, more performant layout
• Simplified API by removing unused props
• Fixed vertical gutter spacing issues
• Improved handling of duplicate items and key management
• Enhanced layout calculation for better stability
• Improved image loading and height calculations

Features

• Added better support for RTL layouts
• Enhanced responsive layout handling
• Improved performance with optimized layout calculations
• Better handling of dynamic content changes
• Added validation for duplicate keys and refs

Dependencies

• Updated all dependencies to latest versions
• Removed unused dependencies
• Simplified build system
• Added support for React 18
• Removed Flow types in favor of simpler JavaScript

Documentation

• Completely revised documentation
• Added new examples for common use cases
• Simplified installation and usage instructions
• Updated API documentation to reflect current features

0.7.1

• Make transform coordinates round to the nearest integer to avoid blurriness. Thank you @xaviergonz

0.7.0

• Add itemComponent props. Thank you @solomonhawk ! #35

0.6.0

• Add rtl props. Thank you @azizghuloum !

0.5.0

• Add horizontal props. Thank you @ilyalesik !

0.4.0

• Add onLayout props. Thanks for @jarib !

0.3.0

• Add gridRef props. Thanks for @mquandalle and @derwydd !

0.2.2

• Fix calculations for percentage columns width #16
  Thanks @mquandalle!
• Migrate from react-addons-transition-group to react-transition-group. #17
• Remove setState warning that occurs after unmounting.

0.2.1

• Support for React v15.5.x ~ (add prop-types package) #2
• Fix lint and typechecking (flowtype)
• Update devDependencies

0.2.0

• Add enableSSR props. Thanks for @egorAva! #7

0.1.1

• Fix transition animation when sort order changed
• Update demo page (Added shuffle button)

0.1.0

New feature

• Support column percentage width

Bugfix

• Change waiting for size calculation of react-sizeme before rendering
• Fix warning when deleted before appear
• Remove propTypes warning when there is no children

0.0.2

• Fix files field in package.json

0.0.1

• First release.