Skip to main content

List Products Grid Block

The ListProductsGrid Component is a fully customizable and accessible grid layout for displaying products built with React and TypeScript. It provides a complete product listing interface with modern design patterns, flexible customization options, and composable sub-components for titles, items, and cards.

πŸš€ Installation​

npm install @nodeblocks/frontend-list-products-grid-block@0.1.2

πŸ“– Usage​

import {ListProductsGrid} from '@nodeblocks/frontend-list-products-grid-block';
function ProductsGridExample() {
    const data: ComponentProps<typeof ListProductsGrid.Items.GridCard>[] = [
        {
            chips: [{ label: 'New' }],
            tags: [{ icon: 'shopping_bag', label: 'Category 1' }],
            subtitleImageUrl: '',
            summary: 'This is a summary of something',
            imageUrl: 'https://unsplash.it/640?random&x=' + Math.random(),
            subtitle: 'Product Card subtitle 1',
            title: 'Product Card Title 1',
            linkProps: { 
                href: '/products/1', 
                onNavigate: () => console.log('Navigating to product 1') 
            }
        },
        {
            chips: [{ label: 'New' }],
            tags: [{ icon: 'shopping_bag', label: 'Category 1' }],
            linkProps: { href: '/my/product/card2', onNavigate: () => {} },
            imageUrl: 'https://unsplash.it/640?random&x=' + Math.random(),
            subtitle: 'Product Card subtitle 2',
            title: 'Product Card Title 2',
        },
        {
            chips: [{ label: 'New' }],
            tags: [{ icon: 'shopping_bag', label: ['Category 1', 'Category 2'] }],
            linkProps: { href: '/my/product/card3', onNavigate: () => {} },
            imageUrl: 'https://unsplash.it/640?random&x=' + Math.random(),
            subtitle: 'Product Card subtitle 3',
            title: 'Product Card Title 3',
        },
    ];

    return (
        <ListProductsGrid
            listProductsGridTitle="Our Products"
            subtitle="Featured Items"
            className="custom-grid">
            <ListProductsGrid.Title />
            <ListProductsGrid.Items>
                {data.map((props, i) => (
                    <ListProductsGrid.Items.GridCard key={i} {...props} />
                ))}
            </ListProductsGrid.Items>
        </ListProductsGrid>
    );
}

πŸ”§ Props Reference​

Main Component Props​

The main ListProductsGrid component inherits all props from the HTML div element (except children which is overridden) and adds:

PropTypeDefaultDescription
listProductsGridTitleReactNodeundefinedMain title for the product list
subtitlestringundefinedSecondary title displayed above the main title
classNamestringundefinedAdditional CSS class name for styling the grid container
childrenBlocksOverrideundefinedCustom block components to override default rendering

Sub-Components​

The ListProductsGrid component provides several sub-components. All sub-components receive their default values from the main component's context and can override these values through props.

ListProductsGrid.Title​

PropTypeDefaultDescription
listProductsGridTitleReactNodeFrom contextContent to display as the main title
subtitlestringFrom contextContent to display as the subtitle
directionenum"column"Flex direction for action buttons
alignItemsenum"stretch"Alignment of items in the container
gapSizeenum"S"Gap between items in the container
childrenReactNodeDefault title layoutCustom content to override the default title layout
classNamestringundefinedAdditional CSS class name for styling the title container

ListProductsGrid.Items​

PropTypeDefaultDescription
directionenum"column"Flex direction for action buttons
alignItemsenum"stretch"Alignment of items in the container
gapSizeenum"S"Gap between items in the container
childrenReactNodeDefault title layoutCustom content to override the default items card layout
classNamestringundefinedAdditional CSS class name for styling the items container

ListProductsGrid.Items.GridCard​

PropTypeDefaultDescription
titlestringundefinedMain title displayed on the card
subtitlestringundefinedSecondary text displayed below the title
summarystringundefinedBrief description or summary text
imageUrlstringundefinedURL of the main image displayed on the card
subtitleImageUrlstringundefinedURL of a small image displayed next to the subtitle
chipsArray<{label: string}>undefinedArray of chip objects to display as badges
tagsArray<{icon: enum, label: string | string[]}>undefinedArray of tag objects with icons and labels
linkProps{href: string, onNavigate: () => void}undefinedNavigation properties for making the card clickable
classNamestringundefinedAdditional CSS class name for styling the card
childrenReactNodeundefinedCustom content to display inside the card (overrides default layout)

πŸ”§ TypeScript Support​

Full TypeScript support with comprehensive type definitions:

import {ListProductsGrid} from '@nodeblocks/frontend-list-products-grid-block';
import {ComponentProps} from 'react';

// Default grid card data structure
interface DefaultGridCardData {
  title?: string;
  subtitle?: string;
  summary?: string;
  imageUrl?: string;
  subtitleImageUrl?: string;
  chips?: Array<{label: string}>;
  tags?: Array<{icon: string, label: string | string[]}>;
  linkProps?: {href: string, onNavigate: () => void};
}

// Extend with custom fields
interface CustomGridCardData extends DefaultGridCardData {
  category?: string;
  price?: number;
  rating?: number;
  customField?: string;
}

const MyProductsGrid = () => {
  const products: ComponentProps<typeof ListProductsGrid.Items.GridCard>[] = [
    {
      title: 'Product 1',
      subtitle: 'Premium Quality',
      summary: 'This is a detailed description of product 1',
      imageUrl: 'https://example.com/product1.jpg',
      chips: [{ label: 'New' }, { label: 'Featured' }],
      tags: [
        { icon: 'shopping_bag', label: 'Electronics' },
        { icon: 'star', label: ['Best Seller', 'Top Rated'] }
      ],
      linkProps: { 
        href: '/products/1', 
        onNavigate: () => console.log('Navigating to product 1') 
      }
    },
    // ... more products
  ];

  return (
    <ListProductsGrid
      listProductsGridTitle="Our Products"
      subtitle="Featured Collection"
      className="custom-grid">
      <ListProductsGrid.Title />
      <ListProductsGrid.Items>
        {products.map((props, index) => (
          <ListProductsGrid.Items.GridCard key={index} {...props} />
        ))}
      </ListProductsGrid.Items>
    </ListProductsGrid>
  );
};

Built with ❀️ using React, TypeScript, and modern web standards.