Documentation Index Fetch the complete documentation index at: https://colossal.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
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 >
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().
Raw cart data from the GraphQL query.
Cart line items with computed prices.
Sum of all line item subtotals.
Whether the cart is being fetched.
Whether the cart drawer/modal is open.
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.
Clear the stored cart ID.
SimpleLineItem Each item in the items array.
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 