Woo Custom Events

Woo runtime events are browser CustomEvent objects. They bubble, so integrations can listen on the originating component, a nearby wrapper, or document.

Use these events for post-mutation integrations such as analytics, mini-cart drawers, and checkout instrumentation. Do not use transient data-ome-state="success" as the integration contract; that state is UI feedback for the control that just finished an async action.

Event Summary

Area	Event	Dispatch target	Detail payload
Cart boot	ome-woo:cart-loaded	First cart display root found, or document.body.	{ cart_summary }
Product add	ome-woo:item-added	Standalone add button or submitted AddToCartForm.	{ product_id, quantity, cart_summary }
Product add	ome-woo:cart-updated	Same target as the successful cart mutation.	{ cart_summary }
Product add	ome-woo:add-to-cart-error	Standalone add button or submitted AddToCartForm.	{ product_id, quantity, error }
Cart item mutation	ome-woo:item-quantity-updated	Cart item quantity input.	{ key, quantity, cart_summary }
Cart item mutation	ome-woo:item-removed	Cart item remove button, or document.body if the button was detached first.	{ key, cart_summary }
Cart item mutation	ome-woo:cart-error	Cart item quantity input or remove button.	{ action, key, quantity?, error }
Checkout	ome-woo:checkout-loaded	Checkout provider, checkout form, checkout notices, or document.body.	{ checkout }
Checkout	ome-woo:checkout-started	Checkout form.	{}
Checkout	ome-woo:checkout-complete	Checkout form.	{ checkout }
Checkout	ome-woo:checkout-error	Checkout form.	{ errors?, phase?, source?, error?, diagnostic? }

Shared Payload Shapes

cart_summary is the live cart summary after the mutation:

type WooCartSummary = {
	item_count: number;
	line_count: number;
};

error is a safe Woo error summary for cart and add-to-cart failures:

type WooErrorSummary = {
	code: string;
	message: string;
	status: number;
	field_keys?: string[];
};

checkout is the current Store API checkout response. Its shape follows Woo's checkout response and can include fields such as order_id, status, order_key, payment_method, payment_result, and __experimentalCart.

diagnostic is present on payment adapter failures when the adapter can provide a safe diagnostic object. It can include methodId, adapterId, provider, paymentType, fieldMode, phase, code, message, details, and sequence.

Cart Boot

ome-woo:cart-loaded

Contract	Value
Dispatch target	First matching cart display root: [data-ome-woo-cart-count], [data-ome-woo-cart-total-field], [data-ome-woo-cart-items], [data-ome-woo-cart-notices], or document.body.
Bubbles	Yes.
When it fires	After Woo cart boot loads and the cart display components are bound.
Detail payload	{ cart_summary: { item_count, line_count } }

Product Add Events

ome-woo:item-added

Contract	Value
Dispatch target	The standalone AddToCartButton, or the submitted AddToCartForm for form-submit buttons.
Bubbles	Yes.
When it fires	After Store API POST /cart/add-item succeeds and the runtime has a fresh cart summary.
Detail payload	{ product_id, quantity, cart_summary: { item_count, line_count } }

Use ome-woo:item-added for post-add integrations. data-ome-state="success" is the visible control state for styling or temporary button copy; it is not the event integration contract.

ome-woo:cart-updated

Contract	Value
Dispatch target	The same element that dispatched the successful cart mutation event.
Bubbles	Yes.
When it fires	After add-to-cart, quantity update, or item removal succeeds.
Detail payload	{ cart_summary: { item_count, line_count } }

ome-woo:cart-updated is useful when the integration only needs to know that the cart changed, not which cart action caused the change.

ome-woo:add-to-cart-error

Contract	Value
Dispatch target	The standalone AddToCartButton, or the submitted AddToCartForm for form-submit buttons.
Bubbles	Yes.
When it fires	After Store API POST /cart/add-item fails.
Detail payload	{ product_id, quantity, error: { code, message, status, field_keys? } }

Cart Item Mutation Events

ome-woo:item-quantity-updated

Contract	Value
Dispatch target	The cart item quantity input.
Bubbles	Yes.
When it fires	After Store API POST /cart/update-item succeeds.
Detail payload	{ key, quantity, cart_summary: { item_count, line_count } }

ome-woo:item-removed

Contract	Value
Dispatch target	The cart item remove button. If that button was detached before the request finished, the event is dispatched from document.body.
Bubbles	Yes.
When it fires	After Store API POST /cart/remove-item succeeds.
Detail payload	{ key, cart_summary: { item_count, line_count } }

ome-woo:cart-error

Contract	Value
Dispatch target	The cart item quantity input for quantity failures, or the remove button for removal failures.
Bubbles	Yes.
When it fires	After Store API quantity update or item removal fails.
Detail payload	{ action, key, quantity?, error: { code, message, status, field_keys? } }, where action is "update-item" or "remove-item".

Checkout Events

ome-woo:checkout-loaded

Contract	Value
Dispatch target	First matching checkout root: [data-ome-woo-checkout-provider], form[data-ome-woo-checkout-form], [data-ome-woo-checkout-notices], or document.body.
Bubbles	Yes.
When it fires	After checkout boot loads and checkout components are bound.
Detail payload	{ checkout }

ome-woo:checkout-started

Contract	Value
Dispatch target	The checkout form.
Bubbles	Yes.
When it fires	After local submit validation passes and before payment adapter preparation or Store API checkout submission.
Detail payload	{}

ome-woo:checkout-complete

Contract	Value
Dispatch target	The checkout form.
Bubbles	Yes.
When it fires	After Store API checkout succeeds. Redirect handling can happen after this event.
Detail payload	{ checkout }

ome-woo:checkout-error

Contract	Value
Dispatch target	The checkout form.
Bubbles	Yes.
When it fires	After local validation, payment adapter preparation, payment result handling, or Store API checkout fails.
Detail payload	Local validation: { errors, phase, source: "local-validation" }. Runtime/payment failure: { error, diagnostic? }.

errors is an array of checkout field errors:

type WooCheckoutFieldError = {
	field_key: string;
	code: "required" | "invalid_email" | "invalid_country" | "invalid_state";
	message: string;
};

phase is "submit" or "update". source is currently "local-validation" when the checkout form blocks submission before Store API checkout.

Mini-Cart Drawer After Add To Cart

This example keeps the Drawer authored as normal OhMyEtch UI. The event listener only opens the real trigger after the Woo add-item event bubbles.

Authored mini-cart drawer

<OmeDrawerTrigger
targeting='{{"targetDrawerId":"store-mini-cart"}}'
content='{{"label":"Cart"}}'
/>

<OmeDrawer
identity='{{"drawerId":"store-mini-cart"}}'
settings='{{"direction":"right","dismissible":true}}'
>
{#slot default}
  <OmeDrawerTitle>Shopping bag</OmeDrawerTitle>
  <OmeWooCartItems>
    {#slot default}
      <OmeWooCartItemImage />
      <OmeWooCartItemTitle />
      <OmeWooCartItemQuantity />
      <OmeWooCartItemRemove />
    {/slot}
    {#slot empty}
      <p>Your cart is empty.</p>
    {/slot}
  </OmeWooCartItems>
  <OmeWooCartTotalsList />
  <OmeDrawerClose>Close</OmeDrawerClose>
{/slot}
</OmeDrawer>

Open the authored drawer after add-to-cart success

document.addEventListener("ome-woo:item-added", () => {
const trigger = document.querySelector(
  '[data-ome-drawer-trigger][data-ome-target-drawer-id="store-mini-cart"]',
);

if (trigger instanceof HTMLButtonElement) {
  trigger.click();
}
});

Listen for ome-woo:item-added, not a new ome-woo:add-to-cart-success event name. The existing success event carries the added product, quantity, and current cart summary.