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.
masonry - Let product descriptions create a staggered rhythm.
featured - Separate one featured product from the collection.
horizontal - Scroll through a horizontal product rail.
carousel - Navigate products with explicit previous and next controls.
compact - Fit shorter product cards into a dense catalog.
editorial - Lead with a product story and supporting items.
collection - Group products by their supplied collection name.
category - Group products by their supplied category.
list - Show product information in compact rows.
asymmetric - Vary item width across a product grid.
bento - Give featured products a larger grid area.
mixed - Pair a primary product with a mixed supporting grid.
minimal - Use a low-chrome catalog presentation.
API
| Prop | Type | Description |
|---|---|---|
variant | ProductGridVariant | Selects one of fourteen compositions; defaults to grid. |
items | readonly ProductGridItem[] | Structured products with stable id, name, and price. |
ProductGridItem.image | CommerceImage | Optional { src, alt, width?, height?, loading? } data. |
ProductGridItem.price | CommerceMoney | Required { amount, currency } value. |
ProductGridItem.compareAtPrice | CommerceMoney | Optional supplied comparison price, rendered with strikethrough. |
ProductGridItem.labels | readonly ProductGridLabel[] | Optional labels with stable IDs and consumer-provided content. |
ProductGridItem.rating | CommerceRating | Optional { value, count?, max? }; max defaults to 5. |
ProductGridItem.category / collection | string | Optional values for category or collection grouping variants. |
ProductGridItem.href | string | Optional product destination. |
ProductGridItem.action | ReactNode | Optional customization slot; the component does not build a cart action. |
locale | string | BCP 47 locale used by Intl.NumberFormat; defaults to en-US. |
| Shared section props | Marketing section props | Header, 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.
| Prop | Required | Default |
|---|---|---|
variant | No | "grid" |
items | Yes | — |
locale | No | "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.
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.