Skip to Content

CommerceBenefitsSection

Display retailer-provided delivery, returns, warranty, checkout, and service information in responsive commerce layouts.

CommerceBenefitsSection presents store information supplied by the consuming application. Benefit titles, descriptions, icons, labels, links, and actions are never generated as policy or trust claims.

Beta API maturity: Beta.

Installation

import {
  CommerceBenefitsSection,
  type CommerceBenefitItem,
} from "@puzzle-ui/pieces";

Variant previews

Each of the ten variants has a separate preview using a fictional homewares retailer. All delivery, return, warranty, and checkout statements are illustrative only.

grid - Show several store policies in a balanced grid.

390 × 844

inline - Present brief service notes in one compact row.

390 × 844

icons - Lead each benefit with its consumer-provided icon.

390 × 844

cards - Separate each retailer-provided benefit into a card.

390 × 844

banner - Use a low-profile strip for store information.

390 × 844

split - Feature one service detail beside supporting items.

390 × 844

compact - Fit short store notes into a dense layout.

390 × 844

trust - Arrange the supplied trust and service information.

390 × 844

shipping - Emphasize items explicitly marked as shipping information.

390 × 844

service - Present retailer service policies as a simple list.

390 × 844

API

PropTypeDescription
variantCommerceBenefitsVariantSelects one of ten compositions; defaults to grid.
itemsreadonly CommerceBenefitItem[]Consumer-provided benefit data with stable id and title.
CommerceBenefitItem.descriptionReactNodeOptional explanatory copy.
CommerceBenefitItem.iconReactNodeOptional consumer-provided icon.
CommerceBenefitItem.kind"shipping" | "returns" | "warranty" | "secure-checkout" | "service"Optional presentation category.
CommerceBenefitItem.labelReactNodeOptional retailer-provided label.
CommerceBenefitItem.hrefstringOptional destination rendered as a native link.
CommerceBenefitItem.actionReactNodeOptional consumer-provided action.
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"grid"
itemsYes—

Usage

const benefits: CommerceBenefitItem[] = [
  {
    id: "delivery",
    title: "Delivery options",
    description: "Describe the regions and delivery options your store supports.",
    icon: <ShippingIcon aria-hidden="true" />,
    kind: "shipping",
    href: "/delivery",
  },
  {
    id: "returns",
    title: "Returns and exchanges",
    description: "Add the return policy published by your retailer.",
    kind: "returns",
  },
];

<CommerceBenefitsSection
  variant="cards"
  title="Helpful store information"
  items={benefits}
/>;

Accessibility

Benefit content remains visible text, links use native anchors, and action slots remain under application control. Provide accessible names for interactive actions and appropriate alternatives for informative icons.

Data and business logic

The component does not promise free shipping, a warranty, secure payment, or a return period by default. It neither retrieves policies nor handles shipping, returns, checkout, or payment.

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 { CommerceBenefitsSection } from "@puzzle-ui/pieces";

type CommerceBenefitsSectionProps = ComponentProps<typeof CommerceBenefitsSection>;

export function CustomizedSection(props: CommerceBenefitsSectionProps) {
  return <CommerceBenefitsSection {...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 { CommerceBenefitsSection } from "@puzzle-ui/pieces";

type CommerceBenefitsSectionProps = ComponentProps<typeof CommerceBenefitsSection>;

export function SectionWrapper(props: CommerceBenefitsSectionProps) {
  return <CommerceBenefitsSection {...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.