Cart

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>

component

Show props

string

required

Your project UID.

string

default:"USD"

Currency code for price formatting.

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().

CartContext

Show state

string | null

Current cart UID.

Cart | null

Raw cart data from the GraphQL query.

SimpleLineItem[]

Cart line items with computed prices.

number

Sum of all line item subtotals.

string

Currency code.

number

Number of line items.

boolean

Whether the cart is being fetched.

boolean

Whether the cart drawer/modal is open.

Show actions

(productUid: string) => Promise<void>

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

(lineItemUid: string) => Promise<void>

Remove a line item.

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

Update a line item’s quantity.

() => void

Set isOpen to true.

() => void

Set isOpen to false.

() => void

Clear the stored cart ID.

SimpleLineItem

Each item in the items array.

SimpleLineItem

Show properties

string

Line item UID.

string

Product UID.

string

Product name.

number

Unit price.

string

Currency code.

string

First media URL.

number

Quantity in cart.

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

Get started

Platform

Agents

Automations

Storefront

Dev Tools

CartProvider

High-level hooks

Low-level hooks

Types

CartContext

SimpleLineItem

Custom storage

Next steps

​CartProvider

​High-level hooks

​Low-level hooks

​Types

​CartContext

​SimpleLineItem

​Custom storage

​Next steps

CartProvider

High-level hooks

Low-level hooks

Types

CartContext

SimpleLineItem

Custom storage

Next steps