Cart

Create and manage shopping carts with add, update, and remove operations.

The cart can be used with Colossal’s hosted checkout or with your own backend and checkout flow.

CartProvider

Wrap your app in CartProvider to manage cart state. It handles cart creation, persistence, and provides actions through context.

import { CartProvider } from "@colossal-sh/storefront-sdk";

<CartProvider storeUid="your-store-uid" currency="USD">
  {children}
</CartProvider>

CartProvider · component

Show props

storeUid · string · required

Your project UID.

currency · string · default: "USD"

Currency code for price formatting.

storage · CartIdStorage · default: "localStorageCartIds"

Storage adapter for cart ID persistence.

High-level hooks

Use useCartContext inside CartProvider for the simplest cart integration.

Hook	Purpose
useCartContext()	Access cart state and actions (add, remove, update)

import { useCartContext, formatPrice } from "@colossal-sh/storefront-sdk";

function Cart() {
  const { items, subtotal, currency, itemCount, addItem, removeItem, updateQuantity } = useCartContext();

  return (
    <div>
      <p>{itemCount} items, {formatPrice(subtotal, currency)}</p>
      {items.map((item) => (
        <div key={item.uid}>
          <span>{item.name} x {item.quantity}</span>
          <button onClick={() => updateQuantity(item.uid, item.quantity + 1)}>+</button>
          <button onClick={() => updateQuantity(item.uid, item.quantity - 1)}>-</button>
          <button onClick={() => removeItem(item.uid)}>Remove</button>
        </div>
      ))}
    </div>
  );
}

addItem automatically creates a new cart if one doesn’t exist yet. If the stored cart is no longer valid (e.g., it expired), it creates a fresh cart and retries.

Low-level hooks

Direct control over cart mutations, for use outside CartProvider.

Hook	Purpose
useCart(cartUid)	Fetch a cart by UID
useCreateCart()	Create a new cart
useAddToCart()	Add a product to a cart
useUpdateCartLine()	Update line item quantity
useRemoveCartLine()	Remove a line item

Types

CartContext

Returned by useCartContext().

context · CartContext

Show state

cartId · string | null

Current cart UID.

cart · Cart | null

Raw cart data from the GraphQL query.

items · SimpleLineItem[]

Cart line items with computed prices.

subtotal · number

Sum of all line item subtotals.

currency · string

Currency code.

itemCount · number

Number of line items.

isLoading · boolean

Whether the cart is being fetched.

isOpen · boolean

Whether the cart drawer/modal is open.

Show actions

addItem · (productUid: string) => Promise<void>

Add a product to the cart. Creates a cart if none exists.

removeItem · (lineItemUid: string) => Promise<void>

Remove a line item.

updateQuantity · (lineItemUid: string, quantity: number) => Promise<void>

Update a line item’s quantity.

openCart · () => void

Set isOpen to true.

closeCart · () => void

Set isOpen to false.

refreshCart · () => void

Clear the stored cart ID.

SimpleLineItem

Each item in the items array.

item · SimpleLineItem

Show properties

uid · string

Line item UID.

productUid · string

Product UID.

name · string

Product name.

price · number

Unit price.

currency · string

Currency code.

imageUrl · string

First media URL.

quantity · number

Quantity in cart.

subtotal · number

Price x quantity.

Custom storage

The default localStorageCartIds stores cart IDs in localStorage keyed by cart-{storeUid}. To use a different storage mechanism, implement the CartIdStorage interface:

import { type CartIdStorage, CartProvider } from "@colossal-sh/storefront-sdk";

const customStorage: CartIdStorage = {
  get(storeUid: string): string | null {
    return sessionStorage.getItem(`cart-${storeUid}`);
  },
  set(storeUid: string, cartId: string | null): void {
    if (cartId === null) {
      sessionStorage.removeItem(`cart-${storeUid}`);
    } else {
      sessionStorage.setItem(`cart-${storeUid}`, cartId);
    }
  },
};

<CartProvider storeUid="..." storage={customStorage}>
  {children}
</CartProvider>

Next steps

• Checkout. Convert the cart into an order with payment
• Cart concepts. Understand the cart lifecycle