Skip to Content

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.

390 × 844

gallery - Give several product images room to breathe.

390 × 844

editorial - Pair product storytelling with a large image.

390 × 844

tabs - Switch between the supplied description, features, and specs.

390 × 844

accordion - Expand product details with accessible disclosures.

390 × 844

specifications - Emphasize a consumer-provided specifications list.

390 × 844

features - Present the supplied product features prominently.

390 × 844

comparison - Compare values explicitly supplied by the retailer.

390 × 844

compact - Keep one primary image beside concise details.

390 × 844

full-width - Use a wider section for images and specification content.

390 × 844

sticky - Keep product media in view beside the details.

390 × 844

media-led - Lead with product imagery and supporting details.

390 × 844

API

PropTypeDescription
variantProductDetailsVariantSelects one of twelve compositions; defaults to split.
productProductDetailsDataProduct data with stable id and name.
product.descriptionReactNodeOptional description.
product.mediareadonly CommerceImage[]Optional images with alternative text.
product.price / compareAtPriceCommerceMoneyOptional supplied currency values; no discount calculation is performed.
product.labelsreadonly ProductGridLabel[]Optional consumer-provided product labels.
product.ratingCommerceRatingOptional supplied rating and count.
product.availabilityReactNodeOptional retailer-provided availability presentation.
product.variantSelectorReactNodeOptional selector slot; the consuming application owns its state and behavior.
product.featuresreadonly ReactNode[]Optional feature list.
product.specificationsreadonly ProductSpecification[]Optional labeled specification values.
product.comparisonProductDetailsComparisonOptional comparison name and explicit row values for the comparison variant.
product.actionsReactNodeOptional consumer-provided product actions.
localestringBCP 47 locale used for currency formatting; defaults to en-US.
Shared section propsMarketing section propsHeader, 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.

PropRequiredDefault
variantNo"split"
productYes—
localeNo"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.