Skip to content
EvolveEvolveEvolve

feature-cart

@evolve-storefront/feature-cart · v1.1.0 · Storybook ↗

The cart and checkout: line items, totals, discount codes, the header badge and add-to-cart. The package ships the data hooks and ready-made parts; your app composes the pages.

Get started

  1. Install the package with the peer dependencies it needs. It comes from the Evolve registry, which needs a one-time sign-in.

    pnpm add @evolve-storefront/feature-cart @labdigital/graphql-fetcher @tanstack/react-query graphql next next-intl react
    Requirements6
    @labdigital/graphql-fetcher>=3
    @tanstack/react-query>=5
    graphql>=16
    next>=16.2.11 <17
    next-intl>=4
    react>=19

  2. Import its styles in the stylesheet where you load Tailwind. Without them the components render unstyled.

    @import "@evolve-storefront/feature-cart/styles.css";

  3. Wrap your app in CartProvider. Setup lists its props.

  4. Add its translations to your message files with evolve messages.

Then render it on a page:

import { CartProvider } from "@evolve-storefront/feature-cart/provider";
import { useCart } from "@evolve-storefront/feature-cart/hooks";
import { Cart, CartEmpty, CartSkeleton } from "@evolve-storefront/feature-cart/cart";


<CartProvider hasSession={hasSession} businessUnitId={businessUnitId}>
  <CartPage />
</CartProvider>;


function CartPage() {
  const { data: cart, isPending } = useCart();


  // Gate on isPending, never isLoading — the cart query is auth-gated, and
  // `isLoading` is `isPending && isFetching`, so it reports false while gated.
  if (isPending) return <CartSkeleton lines={badgeCount} />;
  if (!cart || cart.lineItems.length === 0) return <CartEmpty />;


  return <Cart cart={cart} />;
}

Components

What you place on your pages. Each one has a preview, its props, and how to change its layout.

CartThe cart page.
CartSwitcher"My carts" — a side panel whose stated job is switch carts and create carts, nothing else.
AddToCartScopeOne pending state for every add in its subtree.
CartAddedSheetThe add-to-cart confirmation: mount it once beside CartProvider and every add opens it, on a pending row until the cart answers.
CartAddBundleButtonAdds a product and the extras chosen with it in one call, as a bundle.
CartAddLinesButtonAdd several lines to the active cart in one write, creating a cart where there is none, and say why when the cart refuses.
CartAddProductButtonAdd a product to the cart, including the "no cart yet" path — useAddToCart names the current cart on the wire and lets the server create one only when there is none, so a first add is a single round trip and a second one lands in the cart the first made.
CartApprovalNoticeSays, before the buyer places a business order, that it will wait for approval: which rule, above what amount, and who decides.
CartMinimumOrderNoticeSays how much a business cart still lacks to reach the company's minimum order value, and that a quote can still be requested.
CartChangesNoticeWhat changed in the cart since the buyer last looked, at the top of the cart: sold-out lines, price changes against the price at the time of adding, lowered quantities, and lines an engine removed.
CartCrossSellUp to three products that go with what is in the cart, to place below its lines.
CartBadgeThe header count.
CartQuickAddAdd one product to the active cart by article number or name, on one line: the buyer types, picks a suggestion or keeps what they typed as the SKU, sets the quantity and adds.
QuickOrderOrder by SKU: the buyer pastes or types SKU and quantity lines, or uploads a CSV export, checks them, and sees each line resolved (name, net price, stock) or rejected with the reason.
CheckoutThe checkout: one section open at a time, the others collapsed to a summary or waiting their turn, and the summary aside.

Hooks

62 hooks to read and change the data yourself, for when you build your own UI. The example above only needs useCart. All hooks

Engine support

More in this package

  • Setup and server: what the package needs in your project.
  • Advanced: contexts, graphql documents, data and cache helpers, errors, schemas, other functions and constants, types.