CartSummarySection
Present caller-supplied cart items, quantities, totals, discounts, shipping, and optional checkout actions without order logic.
CartSummarySection is a presentation-only summary of values supplied by the application. It does not update quantities, calculate line totals, create orders, or process payment.
Beta API maturity: Beta.
Installation
import {
CartSummarySection,
type CartSummaryItem,
type CartSummaryTotals,
} from "@puzzle-ui/pieces";Variant previews
Every variant has an independent preview using a fictional coffee shop’s explicitly supplied items and totals.
sidebar - Place supplied totals beside the item list.
compact - Use a short summary without product photos.
full - Show images, quantities, and supplied line totals.
card - Contain the complete summary in a card surface.
sticky - Keep the totals panel in view on wide screens.
checkout - Emphasize an order summary before checkout.
split - Separate items from the totals panel.
minimal - Use a restrained item list and supplied totals.
detailed - Show item descriptions and image details.
mobile - Prioritize a compact, narrow-screen summary.
API
| Prop | Type | Description |
|---|---|---|
variant | CartSummaryVariant | Selects one of ten compositions; defaults to card. |
items | readonly CartSummaryItem[] | Items with unique IDs, names, non-negative integer quantities, and supplied unit prices. |
CartSummaryItem.unitPrice | CommerceMoney | Required per-unit price; it is not multiplied by quantity. |
CartSummaryItem.lineTotal | CommerceMoney | Optional supplied line total; never calculated from quantity. |
CartSummaryItem.image | CommerceImage | Optional image and alternative text. |
CartSummaryItem.description | ReactNode | Optional item detail. |
CartSummaryItem.href | string | Optional item destination. |
totals.subtotal | CommerceMoney | Optional supplied subtotal. |
totals.discounts | readonly CartSummaryAdjustment[] | Optional supplied discount labels and signed amounts. |
totals.shipping | CommerceMoney | Optional supplied shipping amount. |
totals.total | CommerceMoney | Optional supplied total. |
emptyState | ReactNode | Optional empty-cart message; defaults to “Your cart is empty.” |
locale | string | BCP 47 locale used for currency and quantity formatting; defaults to en-US. |
actions | ReactNode | Optional consumer-provided action content; the component does not implement checkout. |
Currency values use locale-aware Intl.NumberFormat. A discount amount should be passed with the sign that the application wants displayed. If an item or cart is empty, the component does not show supplied totals. Quantities must be non-negative safe integers; zero is displayed as supplied.
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 | "card" |
items | Yes | — |
totals | No | — |
emptyState | No | "Your cart is empty." |
locale | No | "en-US" |
Usage
const items: CartSummaryItem[] = [
{
id: "coffee",
name: "House Blend Coffee",
quantity: 2,
unitPrice: { amount: 18, currency: "USD" },
lineTotal: { amount: 36, currency: "USD" },
},
];
const totals: CartSummaryTotals = {
subtotal: { amount: 36, currency: "USD" },
discounts: [
{ id: "welcome", label: "Welcome offer", amount: { amount: -5, currency: "USD" } },
],
shipping: { amount: 0, currency: "USD" },
total: { amount: 31, currency: "USD" },
};
<CartSummarySection
variant="checkout"
items={items}
totals={totals}
actions={<a href="/checkout">Continue</a>}
/>;The sample values are internally consistent only because the application supplied them that way; the component does not verify or derive totals.
Accessibility
Items remain a semantic list, quantities have visible labels, and totals use definition-list semantics. Empty content is announced with a status role. Supplied links and actions should have meaningful accessible names.
Data and business logic
This component is not a cart engine. It does not mutate items, change quantity, calculate subtotal/discount/shipping/tax, validate stock, submit orders, or handle 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 { CartSummarySection } from "@puzzle-ui/pieces";
type CartSummarySectionProps = ComponentProps<typeof CartSummarySection>;
export function CustomizedSection(props: CartSummarySectionProps) {
return <CartSummarySection {...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 { CartSummarySection } from "@puzzle-ui/pieces";
type CartSummarySectionProps = ComponentProps<typeof CartSummarySection>;
export function SectionWrapper(props: CartSummarySectionProps) {
return <CartSummarySection {...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.