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.
inline - Present brief service notes in one compact row.
icons - Lead each benefit with its consumer-provided icon.
cards - Separate each retailer-provided benefit into a card.
banner - Use a low-profile strip for store information.
split - Feature one service detail beside supporting items.
compact - Fit short store notes into a dense layout.
trust - Arrange the supplied trust and service information.
shipping - Emphasize items explicitly marked as shipping information.
service - Present retailer service policies as a simple list.
API
| Prop | Type | Description |
|---|---|---|
variant | CommerceBenefitsVariant | Selects one of ten compositions; defaults to grid. |
items | readonly CommerceBenefitItem[] | Consumer-provided benefit data with stable id and title. |
CommerceBenefitItem.description | ReactNode | Optional explanatory copy. |
CommerceBenefitItem.icon | ReactNode | Optional consumer-provided icon. |
CommerceBenefitItem.kind | "shipping" | "returns" | "warranty" | "secure-checkout" | "service" | Optional presentation category. |
CommerceBenefitItem.label | ReactNode | Optional retailer-provided label. |
CommerceBenefitItem.href | string | Optional destination rendered as a native link. |
CommerceBenefitItem.action | ReactNode | Optional consumer-provided action. |
| 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 | "grid" |
items | Yes | — |
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.