# Woo Components

> Code-backed guide to how OhMyEtch Woo components compose product, cart, and checkout experiences.

<!-- Sources: src/Components/Woo/**; src/Components/Woo/Shared/**; src/Woo/Woo.php; src/Woo/CartItemsDynamicSource.php; src/Woo/WooSelectorDynamicSource.php; client/src/domains/woo/woo-runtime.ts; src/Testing/E2E/Woo/WooScenarioProvider.php; tests/e2e/components/woo/behavior.spec.ts; tests/e2e/components/woo/lifecycle.spec.ts -->

# 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](/woo/how-woo-components-work) for the request and render flow.
- Read [Data Context and Dynamic Sources](/woo/data-context-and-dynamic-sources) before composing loops or using `{item.*}` and `{this.*}`.
- Read [Component Families](/woo/component-families/product-purchase) when authoring a specific UI cluster.
- Read [Recipes](/woo/recipes) for scenario-backed examples.