Skip to Content

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.

390 × 844

compact - Use a short summary without product photos.

390 × 844

full - Show images, quantities, and supplied line totals.

390 × 844

card - Contain the complete summary in a card surface.

390 × 844

sticky - Keep the totals panel in view on wide screens.

390 × 844

checkout - Emphasize an order summary before checkout.

390 × 844

split - Separate items from the totals panel.

390 × 844

minimal - Use a restrained item list and supplied totals.

390 × 844

detailed - Show item descriptions and image details.

390 × 844

mobile - Prioritize a compact, narrow-screen summary.

390 × 844

API

PropTypeDescription
variantCartSummaryVariantSelects one of ten compositions; defaults to card.
itemsreadonly CartSummaryItem[]Items with unique IDs, names, non-negative integer quantities, and supplied unit prices.
CartSummaryItem.unitPriceCommerceMoneyRequired per-unit price; it is not multiplied by quantity.
CartSummaryItem.lineTotalCommerceMoneyOptional supplied line total; never calculated from quantity.
CartSummaryItem.imageCommerceImageOptional image and alternative text.
CartSummaryItem.descriptionReactNodeOptional item detail.
CartSummaryItem.hrefstringOptional item destination.
totals.subtotalCommerceMoneyOptional supplied subtotal.
totals.discountsreadonly CartSummaryAdjustment[]Optional supplied discount labels and signed amounts.
totals.shippingCommerceMoneyOptional supplied shipping amount.
totals.totalCommerceMoneyOptional supplied total.
emptyStateReactNodeOptional empty-cart message; defaults to “Your cart is empty.”
localestringBCP 47 locale used for currency and quantity formatting; defaults to en-US.
actionsReactNodeOptional 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.

PropRequiredDefault
variantNo"card"
itemsYes—
totalsNo—
emptyStateNo"Your cart is empty."
localeNo"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.