Shared Controls and Props

Several Woo families share the same authoring ideas. These props are shared because the runtime shares behavior, not because they are cosmetic conveniences.

UIChoice Selectors

AttributeSelector, ShippingMethodSelector, address country/state fields, and PaymentMethodSelector all use the shared UIChoice runtime.

Prop	Applies to	Meaning
ui.mode	Attribute, shipping, payment	Selects the control structure. Supported modes depend on the component.
ui.aria_label	Attribute, shipping, payment	Accessible name on the selector root.
ui.default_label	Select mode selectors	Trigger text before a selected option is resolved.
ui.html_tag	UIChoice components that expose it	Root element tag for authored structure.

Mode behavior:

Mode	Markup and runtime
select	Renders a trigger and hidden listbox content. Runtime may move content into the shared UIChoice host for positioning.
radio	Renders an in-tree radiogroup with UIChoice indicators.
button-radio	Renders an in-tree radiogroup without the radio indicator.
color-swatch	Attribute Selector radiogroup with a CSS-mapped color visual and honest text fallback.
image-swatch	Attribute Selector radiogroup with a stable variation-owned image or CSS-mapped image and honest text fallback.

Address country/state controls always use the UIChoice select structure. Their listbox content may be moved into the shared UIChoice host for positioning, so the dropdown content and option row visuals come from the address form select_content_class and select_item_class styling props.

Use the mode that matches the customer interaction: select for compact layouts, radio for visible choices with indicators, button-radio for choice buttons without the radio indicator, and swatches when the option is genuinely easier to recognize visually. Swatches keep radio keyboard behavior and accessible option names. They are currently specific to AttributeSelector; shipping, payment, and address selectors retain their documented mode sets.

Content Props

Content props control visible labels and fallback text:

Prop group	Components	Notes
content.label	Add-to-cart button, buy-now button, remove buttons, place-order button	Button text; ARIA labels can mirror it.
content.successMsg	Add-to-cart button	Temporary button text after successful add.
content.show_price and content.price_separator	Shipping selector	Controls shipping rate label composition.
content.show_description	Payment selector	Removes payment method descriptions when false.
content.show_empty_message and content.empty_message	Coupon applied list	Controls the empty coupon message.
content.include_attributes and content.variant_separator	Cart item title, order summary	Controls composed variant title text.

Structure Props

Structure props are for authored HTML semantics, not runtime targeting.

Prop	Applies to	Meaning
structure.root_tag	CartItems, CartAttributeList, totals lists	Root wrapper element.
structure.item_tag	CartItems, CartAttributeList	Row element for item or attribute loops.
structure.empty_tag	CartItems	Empty-state wrapper element.
structure.html_tag	Labeled total atoms	Wrapper element when a total atom shows a label.

Preview Props

Preview props affect deterministic Etch builder output. They do not change live Woo cart or checkout data.

Prop	Applies to	Meaning
preview.rows	CartItems, CartAttributeList, CouponAppliedList	Number of rows shown in builder preview.
preview.empty_state	CartItems, CouponAppliedList	Shows the authored empty state in builder preview.
preview.show_in_builder	Cart and checkout notices	Shows a sample notice in builder preview.
preview.notice_type	Cart and checkout notices	Sets the builder notice type sample.
preview.state	Address form fields	Shows idle or error state in builder preview.
shipping_toggle.preview_checked	Shipping address form	Initial builder state for the different-shipping toggle.
preview.quantity	Product Cart Quantity	Non-mutating confirmed-quantity sample shown only in the Etch editor.

Class Props

Woo components rely heavily on class props so authors can style each atomic part without changing runtime selectors.

Woo class prop values are Etch class style IDs. Values passed to props such as styling.class, styling.item_class, or styling.input_class must resolve to registered Etch styles in etch_styles with class selectors. A matching selector in a global stylesheet is not enough.

For example, a storefront stylesheet can load .store-purchase, .store-choice, .cart-list, .coupon-form, .shipping-choice, .checkout-provider, .address-form__input, or .order-summary-box, but those IDs are unavailable to Woo class props until they are registered as Etch styles. This usually matters for IDs used only through ComponentBlock class props, because they never appear as static builder classes for Etch to discover.

Runtime selectors use data-ome-* attributes. JavaScript, lifecycle behavior, and assertions should target those attributes. Class props should be treated as styling hooks only.

Important shared style groups:

Group	Components
UIChoice styles	Attribute selector, shipping selector, payment selector, address country/state controls.
Control default styles	Coupon input and checkout fields.
Cart totals styles	TotalsSubtotal, TotalsDiscount, TotalsShipping, TotalsTax, TotalsTotal.
Address form field styles	Billing and shipping address forms.

Billing and shipping address forms expose select_content_class and select_item_class for the portaled country/state UIChoice listbox. Use those props for dropdown content and option-row styling instead of targeting fixed positioning hooks.

Use this compact map to discover the style IDs a project-owned Woo stylesheet needs to register:

Family	Class prop paths to check
Product purchase	ProductCartQuantity styling.wrapper_class, styling.input_class, styling.decrease_button_class, styling.value_class, styling.increase_button_class; AddToCartForm styling.class; AddToCartButton styling.button_class, styling.wrapper_class, styling.input_class, styling.decrement_button_class, styling.value_class, styling.increment_button_class; AttributeSelector UIChoice props plus styling.swatch_class, styling.swatch_label_class, styling.swatch_fallback_class, and styling.selected_indicator_class; VariationResetButton styling.class; BuyNowButton styling.class.
Cart items	CartItems styling.root_class, styling.item_class, styling.empty_class; cart item atoms styling.class; CartItemQuantity styling.wrapper_class, styling.label_class, styling.input_class, styling.preview_class, styling.decrease_button_class, styling.value_class, styling.increase_button_class; cart attribute list/name/value class props.
Coupons	CouponForm styling.class, styling.input_class; CouponAppliedList styling.root_class, styling.item_class, styling.code_class, styling.empty_class; CouponRemoveButton styling.class.
Cart totals	CartTotalsList and OrderSummaryTotalsList styling.list_class; total atoms styling.class, styling.label_class, styling.value_class.
Checkout shell	CheckoutProvider, CheckoutForm, CheckoutNotices, PlaceOrderButton, TermsCheckbox, and PaymentGatewayFieldsSlot styling.class.
Address forms	Billing and shipping forms styling.class, styling.items_class, styling.item_class, styling.field_class, styling.label_text_class, styling.legend_class, styling.error_class, styling.input_class, styling.select_content_class, styling.select_item_class; shipping toggle styling.toggle_class.
Shipping	ShippingMethodSelector UIChoice props: styling.class, styling.item_class, styling.label_class, styling.trigger_class, styling.trigger_label_class, styling.content_class, styling.indicator_class.
Payment	PaymentMethodSelector UIChoice props: styling.class, styling.item_class, styling.label_class, styling.trigger_class, styling.trigger_label_class, styling.content_class, styling.indicator_class.
Order summary	OrderSummary styling.class, styling.items_class, styling.item_class, styling.product_title_class, styling.details_class, styling.quantity_class, styling.price_class, styling.row_class; atom class props when using atom modes.

State Attributes

Woo runtime state is reflected through data-ome-state.

State	Common surfaces
idle	Ready forms, buttons, notice regions without active feedback.
loading, updating, processing	Checkout store states.
success	Successful add-to-cart, coupon, quantity, remove, and checkout submit actions.
error	Local validation, Store API errors, notice regions.
has-items, empty	Cart count, cart items, coupon list, quantity preview.
ready, hidden, text	Address fields and shipping selector availability.
unavailable, invalid	Product purchase forms.
loading, unresolved, ready, ambiguous	Provider-scoped Product Cart Quantity lifecycle.