Skip to Content

ProductGridSection

Display structured ecommerce products with responsive layouts, localized prices, optional ratings, labels, links, and actions.

ProductGridSection presents product data supplied by your application. Product cards have a structured API for names, images, prices, comparison prices, labels, ratings, categories, collections, links, and optional action slots.

Beta API maturity: Beta.

Installation

import {
  ProductGridSection,
  type ProductGridItem,
} from "@puzzle-ui/pieces";

Variant previews

Each of the fourteen layouts has a separate preview using a fictional outdoor retailer’s catalog.

grid - Browse a balanced product catalog.

390 × 844

masonry - Let product descriptions create a staggered rhythm.

390 × 844

featured - Separate one featured product from the collection.

390 × 844

horizontal - Scroll through a horizontal product rail.

390 × 844

carousel - Navigate products with explicit previous and next controls.

390 × 844

compact - Fit shorter product cards into a dense catalog.

390 × 844

editorial - Lead with a product story and supporting items.

390 × 844

collection - Group products by their supplied collection name.

390 × 844

category - Group products by their supplied category.

390 × 844

list - Show product information in compact rows.

390 × 844

asymmetric - Vary item width across a product grid.

390 × 844

bento - Give featured products a larger grid area.

390 × 844

mixed - Pair a primary product with a mixed supporting grid.

390 × 844

minimal - Use a low-chrome catalog presentation.

390 × 844

API

PropTypeDescription
variantProductGridVariantSelects one of fourteen compositions; defaults to grid.
itemsreadonly ProductGridItem[]Structured products with stable id, name, and price.
ProductGridItem.imageCommerceImageOptional { src, alt, width?, height?, loading? } data.
ProductGridItem.priceCommerceMoneyRequired { amount, currency } value.
ProductGridItem.compareAtPriceCommerceMoneyOptional supplied comparison price, rendered with strikethrough.
ProductGridItem.labelsreadonly ProductGridLabel[]Optional labels with stable IDs and consumer-provided content.
ProductGridItem.ratingCommerceRatingOptional { value, count?, max? }; max defaults to 5.
ProductGridItem.category / collectionstringOptional values for category or collection grouping variants.
ProductGridItem.hrefstringOptional product destination.
ProductGridItem.actionReactNodeOptional customization slot; the component does not build a cart action.
localestringBCP 47 locale used by Intl.NumberFormat; defaults to en-US.
Shared section propsMarketing section propsHeader, root element, theme, native attributes, and children.

Prices use locale-aware Intl.NumberFormat currency formatting. Comparison prices are shown as supplied; the component does not calculate savings, discounts, or totals. Unsupported currency codes, invalid locales, and non-finite amounts throw instead of rendering a fabricated value. Missing or failed images show a placeholder; image alternatives should describe the supplied image.

Required and default values

Requiredness follows the exported TypeScript type. A dash means no component-level default is applied; variant-specific requirements are described in the API table above.

PropRequiredDefault
variantNo"grid"
itemsYes—
localeNo"en-US"

Usage

const products: ProductGridItem[] = [
  {
    id: "ridge-shell",
    name: "Ridge Shell Jacket",
    image: {
      src: "/products/ridge-shell.jpg",
      alt: "Olive weatherproof shell jacket",
    },
    price: { amount: 148, currency: "USD" },
    compareAtPrice: { amount: 168, currency: "USD" },
    labels: [{ id: "new", content: "New" }],
    rating: { value: 4.8, count: 36 },
    category: "Outerwear",
    collection: "Trail essentials",
    href: "/products/ridge-shell",
  },
];

<ProductGridSection
  variant="category"
  title="Field-tested everyday gear"
  items={products}
  locale="en-US"
/>;

Product filters

Filtering remains application-owned. This preview keeps the selected category in React state and passes only the matching products to ProductGridSection.

390 × 844

Accessibility

Product names remain headings, product destinations are native links, and carousel navigation uses labeled buttons with disabled boundary states. Ratings include a text equivalent; they are not conveyed by color alone. Product actions are consumer-provided so their labels and behavior remain under application control.

Data and business logic

The component does not fetch products, inventory, ratings, or prices. It has no cart, checkout, stock, or payment behavior; the application supplies every product field.

Customization

Use the component's className and documented slots to adapt the composition. Prefer a caller-provided ReactNode for media, actions, or controls rather than adding domain behavior to the section.

import type { ComponentProps } from "react";
import { ProductGridSection } from "@puzzle-ui/pieces";

type ProductGridSectionProps = ComponentProps<typeof ProductGridSection>;

export function CustomizedSection(props: ProductGridSectionProps) {
  return <ProductGridSection {...props} className={[props.className, "brand-section"].filter(Boolean).join(" ")} />;
}

Responsive behavior

Use the preview device selector to review mobile, tablet, and desktop widths. The built-in variant controls section structure; ensure application-provided media, form controls, and children can shrink or wrap without horizontal overflow. Use the existing responsive breakpoints in scoped CSS when the consuming layout needs a product-specific adjustment.

Theme support

The section consumes semantic variables from @puzzle-ui/theme and inherits active or scoped themes. Wrap the application with Theme, and use semantic roles such as text, surface, border, and primary for local overrides. Avoid hard-coded colors, spacing, radii, and shadows.

.brand-section {
  color: var(--puzzle-color-text);
  background: var(--puzzle-color-surface);
  border-color: var(--puzzle-color-border);
}

Composition

Compose this section with the UI primitives named in its API and use the documented slots for consumer-owned controls or media. Keep data fetching, routing, validation, permissions, and persistence in the application. The children slot is intended for additional content that belongs with this section, not as a substitute for its typed data model.

TypeScript example

The package exports this component from its root. Derive a wrapper's exact prop type from the public component rather than widening it:

import type { ComponentProps } from "react";
import { ProductGridSection } from "@puzzle-ui/pieces";

type ProductGridSectionProps = ComponentProps<typeof ProductGridSection>;

export function SectionWrapper(props: ProductGridSectionProps) {
  return <ProductGridSection {...props} />;
}

Framework compatibility

The section is router-independent. Static compositions can be server-rendered; place callback-driven interactions in the framework's client boundary. See Next.js and TanStack Start integration for runnable framework examples and SSR guidance.