Section D
Cart
The cart is a client store synchronised through Shopify Standard Actions. Mutations apply an optimistic projection immediately, track pending entities, and reconcile when the server answers. Inspect the live store and drive it below; the drawer and /cart use the same contract.
Cart store, mutations & optimistic updates
Live view of useCart() state: lines, pending sets, errors, revalidating. Buttons call window.Shopify.actions.updateCart(), the same path code-driven changes use.
- Hydrogen API
createCartComponentsuseCartuseCartFormuseCartActions().refreshwindow.Shopify.actions.updateCartwindow.Shopify.actions.openCart- Data
- Mock cart engine (server-side, in memory)
- Docs
.claude/skills/hydrogen-cart-ui/SKILL.md
{
"loading": true,
"pending": {
"lines": [],
"discountCodes": [],
"cost": false,
"note": false,
"attributes": false
},
"errors": {
"network": [],
"cart": [],
"lines": []
},
"data": {
"id": null,
"totalQuantity": 0,
"cost": {
"subtotalAmount": {
"amount": "0",
"currencyCode": ""
},
"totalAmount": {
"amount": "0",
"currencyCode": ""
},
"checkoutChargeAmount": {
"amount": "0",
"currencyCode": ""
}
},
"discountCodes": [],
"note": "",
"lines": []
}
}export const { CartProvider, useCart, useCartForm } = createCartComponents<typeof cartHandlers>();
// root loader: non-blocking bootstrap, envelope not unwrapped
const cart = cartHandlers.get({ storefrontClient }).then(({ data }) => data);
<CartProvider initialData={loaderData.cart}>…</CartProvider>
// line form contract
<form {...formProps()}>
<button {...register("set")} />
<input type="hidden" {...register("lineId", { value: line.id })} />
<input {...register("quantity", { value: line.quantity, interactive: true })} />
<button {...register("increase")} /> <button {...register("remove")} />
</form>Server-driven cart & progressive enhancement
Without JavaScript, every cart form posts natively to /api/cart, which sets the cart cookie. /cart server-renders the resolved cart.
- Hydrogen API
createCartServerHandlerscreateCartCookiegetCartId- Data
- Any
- Docs
.claude/skills/hydrogen-cart-ui/SKILL.md
See it in the store:Full cart page
Cart drawer
Native <dialog> with showModal(), closedby="any", @starting-style animation and CSS scroll lock, wired to Standard Actions openCart.
- Hydrogen API
window.Shopify.actions.openCart.configure- Data
- Any
- Docs
.claude/skills/hydrogen-cart-drawer/SKILL.md
Discounts, gift cards & out-of-band mutations
Discount codes use the cart form contract. Gift cards (cartGiftCardCodesUpdate) aren't wrapped by the handlers: the /cart action runs the mutation, then calls refresh().
- Hydrogen API
register('discount-apply')useCartActions().refresh- Data
- Mock discount & gift card rules
- Docs
.claude/skills/hydrogen-cart-ui/SKILL.md
See it in the store:Try codes on /cart