Skip to main content

Cart Page

A cart page lets customers review products, change quantities, remove items, apply coupons, choose shipping, and move to checkout.

Minimum Structure​

Cart page
  CartNotices
  CartItems
    CartItemImage
    CartItemTitle
    CartAttributeList
      CartAttributeName
      CartAttributeValue
    CartItemPrice
    CartItemQuantity
    CartItemSubtotal
    CartItemRemove
    Empty slot
  CouponForm
  CouponAppliedList
    CouponRemoveButton
  ShippingMethodSelector
  CartTotalsList
    CartAmount (items subtotal)
    CartAmount (discount)
    CartAmount (fees)
    CartAmount (shipping)
    CartAmount (tax)
    CartAmount (final total)
  Checkout link or button
Editable cart rows with totals
<OmeWooCartNotices />

<OmeWooCartItems>
{#slot default}
  <OmeWooCartItemImage />
  <OmeWooCartItemTitle />
  <OmeWooCartAttributeList>
    {#slot default}
      <OmeWooCartAttributeName />
      <OmeWooCartAttributeValue />
    {/slot}
  </OmeWooCartAttributeList>
  <OmeWooCartItemQuantity />
  <OmeWooCartItemSubtotal />
  <OmeWooCartItemRemove />
{/slot}
{#slot empty}
  Your cart is empty.
{/slot}
</OmeWooCartItems>

<OmeWooCouponForm />
<OmeWooCouponAppliedList>
{#slot default}
  <OmeWooCouponRemoveButton />
{/slot}
</OmeWooCouponAppliedList>

<OmeWooShippingMethodSelector ui='{{"mode":"button-radio","aria_label":"Choose shipping"}}' />

<OmeWooCartTotalsList>
<OmeWooCartAmount
  amount='{{"measure":"items_subtotal","tax_presentation":"store"}}'
  content='{{"show_label":true,"label":""}}'
/>
<OmeWooCartAmount
  amount='{{"measure":"discount","tax_presentation":"store"}}'
  content='{{"show_label":true,"label":""}}'
/>
<OmeWooCartAmount
  amount='{{"measure":"fees","tax_presentation":"store"}}'
  content='{{"show_label":true,"label":""}}'
/>
<OmeWooCartAmount
  amount='{{"measure":"shipping","tax_presentation":"store","pending_text":"Not calculated"}}'
  content='{{"show_label":true,"label":""}}'
/>
<OmeWooCartAmount
  amount='{{"measure":"tax"}}'
  content='{{"show_label":true,"label":""}}'
/>
<OmeWooCartAmount
  amount='{{"measure":"final_total"}}'
  content='{{"show_label":true,"label":""}}'
/>
</OmeWooCartTotalsList>

Step 1: Add Cart Rows​

CartItems renders the current Store API cart items into the default slot. Cart item atom components do not query global cart state by themselves; they read the row context that CartItems hydrates.

This is why item atoms should be authored inside the CartItems default slot:

AtomRow value
CartItemImageCurrent item image and alt fallback.
CartItemTitleCurrent item title, optionally with attributes.
CartAttributeListCurrent item variation/attribute list.
CartItemPriceCurrent item unit price text.
CartItemQuantityCurrent item quantity input and update action.
CartItemSubtotalCurrent item subtotal text.
CartItemRemoveCurrent item remove action.

If the cart becomes empty, CartItems swaps to the empty slot.

Step 2: Let Row Actions Refresh The Cart​

CartItemQuantity and CartItemRemove both send Store API cart mutation requests through the cart store. After a successful mutation, the normalized cart response updates:

  • cart item rows,
  • CartCount,
  • coupon list,
  • shipping rates,
  • cart total atoms,
  • notices.

Quantity edits are local drafts until Woo confirms them. Rapid same-row edits collapse to the newest absolute quantity, while different cart operations retain FIFO order. The quantity input stays editable during its short debounce; the shared count and totals do not change optimistically. Debounced-away and already-satisfied targets emit no events. Every real authoritative response emits ome-woo:item-quantity-updated followed by ome-woo:cart-updated, but the control shows and announces success only when the latest target is confirmed.

Set configuration.counter_presentation="stepper" on CartItemQuantity when the design needs decrease and increase buttons around a read-only count. The default remains the released number input. Both presentations use the same exact-line setter and Woo-provided minimum, maximum, multiple, editability, and sold-individually constraints; neither turns zero into removal.

Style local progress with data-ome-woo-mutation-phase="debouncing|queued|pending|success|error|idle". Existing data-ome-state="loading|success|error|idle" selectors continue to work.

Step 3: Add Coupons​

CouponForm applies a coupon code. CouponAppliedList renders the current applied coupons, and CouponRemoveButton belongs inside each coupon row. The cart demo keeps CartNotices near the top of the page so cart errors share one cart-level feedback region. If a page omits Cart Notices, the runtime announces the final safe error through one visually hidden assertive fallback; it does not create duplicate feedback when Cart Notices is authored. Final confirmed quantity and removal results use one polite announcement; intermediate targets and internal scheduling phases are not narrated.

Step 4: Add Shipping And Totals​

ShippingMethodSelector uses the same UIChoice-backed modes as checkout selectors. Use it when the cart needs a selectable shipping rate before checkout. The selected Store API shipping rate refreshes total values.

CartTotalsList renders authored total rows. For new work, add one CartAmount per shopper measure and reorder or wrap those rows as needed. tax_presentation="store" follows the WooCommerce cart tax-display setting for subtotal, discount, fees, and shipping; explicit including_tax and excluding_tax presentations are also available for those four measures.

Shipping has two intentionally different zero-like cases. Calculated free shipping renders the formatted currency zero. Required shipping that has not been calculated renders Not calculated with data-ome-state="pending"; the direct final total remains visible with data-ome-state="estimated" until shipping resolves.

TotalsSubtotal, TotalsDiscount, TotalsShipping, TotalsTax, and TotalsTotal remain available as unchanged legacy atoms for existing designs. Do not silently replace saved atoms: their flat raw fields and compatibility formatting are not equivalent to Cart Amount's shopper-facing tax and pending-state behavior.

The checkout URL should point to the page assigned in WooCommerce as woocommerce_checkout_page_id. Read Woo Template Integration Contract before building a starter that owns cart and checkout routes.

Next References​