Woo Components

Woo components are Etch components that render WooCommerce product, cart, and checkout UI while keeping WooCommerce as the source of truth. They do not replace Woo's cart, checkout, product, shipping, payment, or order systems. They expose those systems as composable Etch blocks.

The docs are organized in three layers:

Layer	Use it for
System docs	Runtime behavior, data sources, Store API flow, checkout fields, and native Woo hook compatibility.
Component families	Connected component clusters, such as product purchase, cart items, totals, coupons, and checkout shell.
Flow guides	Practical product archive, single product, cart, checkout, and demo-store compositions backed by E2E/demo fixtures.

Mental Model

Woo components split into four working areas:

Area	Core components	Data source
Product purchase	AddToCartForm, AddToCartButton, AttributeSelector, BuyNowButton	Product dynamic data from omewoo plus Store API cart mutations.
Cart state	CartCount, CartNotices, CartItems, cart item atoms, totals, coupons, shipping selector	Server-side cartItems, cartSummary, cartTotals, cartCoupons, then live Store API cart state.
Checkout	CheckoutProvider, CheckoutForm, address forms, payment selector, terms, notices, place order	Localized checkout field schema plus Store API checkout state.
Demo flow	Product archive, single product, cart page, checkout page	WooDemoStoreBuilder seeds products, variations, media, templates, pages, styles, and preview URLs.

Relationships

The most important rule is composition scope. Some components can work alone, and others read from a parent or a dynamic source.

Component family	Relationship
Product purchase	AddToCartForm owns the submitted product and variation state. AttributeSelector, form-submit AddToCartButton, and BuyNowButton are authored inside its default slot.
Cart items	CartItems owns the item loop. CartItemImage, CartItemTitle, CartItemPrice, CartItemSubtotal, CartItemQuantity, CartItemRemove, and CartAttributeList read the current row.
Cart attributes	CartAttributeList loops the selected variation attributes for a cart item. CartAttributeName and CartAttributeValue read each attribute row.
Totals	CartTotalsList and OrderSummaryTotalsList provide layout. The total atoms render total_items, total_discount, total_shipping, total_tax, and total_price.
Coupons	CouponForm mutates the cart. CouponAppliedList renders active coupon rows. CouponRemoveButton belongs inside each coupon row.
Checkout	CheckoutProvider scopes checkout UI. CheckoutForm serializes fields and submits. Address forms, payment selector, terms, notices, and place-order controls belong inside that checkout scope.
Order summary	OrderSummary renders read-only cart rows and totals for checkout; it intentionally reuses cart item atoms and totals atoms.

Runtime Boundary

The first visible state is server-rendered whenever the component has enough Woo data during render. Runtime then updates live nodes in place from Store API responses. Repeated rows and inactive branches use <template> elements as inert blueprints, not as visible UI.

Notices are the main exception: CartNotices and CheckoutNotices are runtime-updated regions because they render user feedback from async Store API mutations and local validation.

Native Woo Compatibility

The Woo components use the Store API for cart and checkout actions, but native Woo hooks still run. The lifecycle E2E suite verifies:

Flow	Native hooks proved by E2E
Add to cart blocked	woocommerce_add_to_cart_validation can block mutation and render a Woo notice.
Add to cart allowed	woocommerce_add_cart_item_data, woocommerce_add_to_cart_validation, woocommerce_add_cart_item, and woocommerce_add_to_cart fire for Etch form submissions.
Pricing	woocommerce_before_calculate_totals and woocommerce_cart_calculate_fees change rendered totals.
Checkout	Store API order creation runs woocommerce_store_api_checkout_update_order_from_request, woocommerce_new_order, woocommerce_rest_checkout_process_payment_with_context, and order status hooks.

Start Here

• Read How Woo Components Work for the request and render flow.
• Read Data Context and Dynamic Sources before composing loops or using {item.*} and {this.*}.
• Read Component Families when authoring a specific UI cluster.
• Read Recipes for scenario-backed examples.