Skip to content
Kotao Developers

Cart & Smart Cart

The cart lives server-side; the SDK gives you a handler, form-based mutations, and optimistic UI so the storefront feels instant.

The cart handler

Section titled “The cart handler”

The scaffold’s Worker entry creates one cart per visitor via createCartHandler — identified by a cookie (CART_ID_COOKIE), readable in any loader through the context. The cart GraphQL documents ship as @kotao/storefront/cart-documents.

Mutating: CartForm

Section titled “Mutating: CartForm”

Cart writes are progressive-enhancement forms:

import { CartForm } from "@kotao/storefront/react";


<CartForm
  action={CartForm.ACTIONS.LinesAdd}
  inputs={{ lines: [{ merchandiseId: variantId, quantity: 1 }] }}
>
  <button type="submit">Add to cart</button>
</CartForm>;

The available actions (CART_FORM_ACTIONS) cover add/update/remove lines, discount codes, and attributes. Your cart route’s action dispatches them to the cart handler.

Line-item properties — personalization inputs like an engraving — travel as attributes on the line. They follow the line through the drawer, the checkout summary, and onto the order.

Optimistic UI

Section titled “Optimistic UI”
  • useOptimisticCart(cart) — merges in-flight CartForm submissions into the cart you render, so quantities and totals update before the server responds.
  • useOptimisticVariant / OptimisticInput — the same idea for variant selection and custom inputs.

Smart Cart: the platform drawer

Section titled “Smart Cart: the platform drawer”

Kotao ships a configurable cart drawer (upsells, free-shipping bar, BOGO presentation) that merchants manage in the Workspace — no theme code. Trigger it after an add-to-cart with:

import { openSmartCart } from "@kotao/storefront/react";


openSmartCart();

If the merchant hasn’t enabled Smart Cart, keep a /cart route as the fallback — the scaffold’s structure already does.