1.0.2 • Published 4 months ago

@zapperwing/pinterest-view v1.0.2

Weekly downloads
-
License
MIT
Repository
github
Last release
4 months ago

pintrest-view

npm version npm downloads

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

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}
    >
      <div key="item1">First Item</div>
      <div key="item2">Second Item</div>
      <div key="item3">Third Item</div>
    </StackGrid>
  );
};

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
    >
      {items.map(item => (
        <YourCustomCard
          key={item.id.toString()} // Unique key is required
          title={item.title}
          content={item.content}
        />
      ))}
    </StackGrid>
  );
};

Tips for Custom Components

  1. Height Calculation: The grid automatically detects the rendered height of your components. No special configuration 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

PropertyTypeDefaultDescription
classNamestringundefinedAdditional CSS class for the grid container
styleobject{}Additional styles for the grid container
gridReffunctionnullRef callback to access the grid instance
componentstring"div"HTML tag for the grid container
itemComponentstring"span"HTML tag for grid items
columnWidthnumber \| string150Width of each column (px or percentage). Example: 150 or "33.33%"
gutterWidthnumber5Horizontal spacing between items (px)
gutterHeightnumber5Vertical spacing between items (px)
monitorImagesLoadedbooleanfalseWhether to monitor and reflow when images load
enableSSRbooleanfalseEnable server-side rendering support
onLayoutfunctionnull