ProductDetailsSection
Present structured product descriptions, imagery, specifications, selectors, features, comparison data, and caller-supplied availability.
ProductDetailsSection presents one product using structured data. It supports description, media, localized prices, feature and specification lists, a consumer-rendered selector slot, availability content, actions, and optional comparison data.
Beta API maturity: Beta.
Installation
import {
ProductDetailsSection,
type ProductDetailsData,
} from "@puzzle-ui/pieces";Variant previews
Each of the twelve variants has a separate preview using a fictional home and kitchen product.
split - Place product media beside its details.
gallery - Give several product images room to breathe.
editorial - Pair product storytelling with a large image.
tabs - Switch between the supplied description, features, and specs.
accordion - Expand product details with accessible disclosures.
specifications - Emphasize a consumer-provided specifications list.
features - Present the supplied product features prominently.
comparison - Compare values explicitly supplied by the retailer.
compact - Keep one primary image beside concise details.
full-width - Use a wider section for images and specification content.
sticky - Keep product media in view beside the details.
media-led - Lead with product imagery and supporting details.
API
| Prop | Type | Description |
|---|---|---|
variant | ProductDetailsVariant | Selects one of twelve compositions; defaults to split. |
product | ProductDetailsData | Product data with stable id and name. |
product.description | ReactNode | Optional description. |
product.media | readonly CommerceImage[] | Optional images with alternative text. |
product.price / compareAtPrice | CommerceMoney | Optional supplied currency values; no discount calculation is performed. |
product.labels | readonly ProductGridLabel[] | Optional consumer-provided product labels. |
product.rating | CommerceRating | Optional supplied rating and count. |
product.availability | ReactNode | Optional retailer-provided availability presentation. |
product.variantSelector | ReactNode | Optional selector slot; the consuming application owns its state and behavior. |
product.features | readonly ReactNode[] | Optional feature list. |
product.specifications | readonly ProductSpecification[] | Optional labeled specification values. |
product.comparison | ProductDetailsComparison | Optional comparison name and explicit row values for the comparison variant. |
product.actions | ReactNode | Optional consumer-provided product actions. |
locale | string | BCP 47 locale used for currency formatting; defaults to en-US. |
| Shared section props | Marketing section props | Header, root element, theme, native attributes, and children. |
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 | "split" |
product | Yes | — |
locale | No | "en-US" |
Usage
const product: ProductDetailsData = {
id: "pour-over",
name: "Stoneware Pour-over Set",
description: "A hand-finished dripper for a slower morning ritual.",
media: [
{
src: "/products/pour-over.jpg",
alt: "Stoneware pour-over set with a ceramic cup",
},
],
price: { amount: 68, currency: "USD" },
availability: <p>Availability copy supplied by the retailer.</p>,
variantSelector: (
<label>
Glaze
<select defaultValue="chalk">
<option value="chalk">Chalk</option>
<option value="sand">Sand</option>
</select>
</label>
),
specifications: [
{ id: "material", label: "Material", value: "Stoneware and steel" },
],
};
<ProductDetailsSection
variant="tabs"
product={product}
locale="en-US"
/>;tabs uses the UI package’s accessible tabs; accordion uses its accessible accordion. Comparison rows are rendered exactly as supplied. Availability, selectors, descriptions, and actions are optional and are never inferred from an external service.
Accessibility
Use descriptive image alternatives, associate native selectors with labels, and ensure action slots have accessible names. Tab and accordion variants use the UI package’s keyboard behavior. Comparison uses a semantic table with scoped headers.
Data and business logic
The application supplies product data and owns selectors, availability, pricing, and actions. No product lookup, inventory query, purchase, or payment logic is included.
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 { ProductDetailsSection } from "@puzzle-ui/pieces";
type ProductDetailsSectionProps = ComponentProps<typeof ProductDetailsSection>;
export function CustomizedSection(props: ProductDetailsSectionProps) {
return <ProductDetailsSection {...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 { ProductDetailsSection } from "@puzzle-ui/pieces";
type ProductDetailsSectionProps = ComponentProps<typeof ProductDetailsSection>;
export function SectionWrapper(props: ProductDetailsSectionProps) {
return <ProductDetailsSection {...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.
Related components
PricingSection
Compose subscription and usage-based SaaS plans with explicit billing options, accessible comparisons, and optional calculators.
ProductGallerySection
Present structured product images in responsive ecommerce galleries with thumbnail navigation, keyboard controls, optional zoom, and a lightbox.