Cart events

Every event the mini-cart emits or listens for, with payloads, plus the custom elements that make up the drawer.

src/entrypoints/mini-cart/internals/core.ts defines every event name in the CartEvents constant and every payload type in the CartEventDetailMap interface. A new event needs an entry in both.

All events are CustomEvents dispatched on window. Every payload that CartEventBus.emit sends also has an external boolean, which is true when code outside the mini-cart's internals started the action.

Commands you can dispatch

Dispatch these to change the cart from any code on the page. They get the same request queueing and stale-key recovery as the drawer's own controls.

Event	Payload
`mini-cart:get`	none
`mini-cart:add`	`{ items: [{ id, quantity, properties }], sections? }`
`mini-cart:change`	`{ id \| line, quantity, properties?, sections? }`
`mini-cart:update`	`{ note?, attributes?, discount?, sections? }` or `{ updates: { [line]: qty } }`
`mini-cart:clear`	none

window.dispatchEvent(
  new CustomEvent('mini-cart:add', {
    detail: { items: [{ id: 123456789, quantity: 1 }] },
  }),
);

Lifecycle events you can listen for

Event	Payload
`cart:add:start`	The add payload
`cart:add:success`	`{ payload, cart }`
`cart:add:error`	`{ payload, error }`
`cart:change:start`	The change payload
`cart:change:success`	`{ payload, cart }`
`cart:change:error`	`{ payload, error }`
`cart:update:start`	The update payload
`cart:update:success`	`{ payload, cart }`
`cart:update:error`	`{ payload, error }`
`cart:clear:start`	none
`cart:clear:success`	`{ cart? }`. The cart is optional because the interceptor can emit this
`cart:clear:error`	`{ error }`

Change notifications

Event	Payload	Notes
`cart:changed`	`{ cart, reason? }`	Emitted for every change, including writes by other apps
`cart:changed:debounced`	`{ cart, reason? }`	The same event, debounced. Use this one for rendering

reason is one of add, change, update, clear or get.

Render from cart:changed:debounced. A burst of quantity changes emits cart:changed many times, and rendering on each one makes the drawer flicker.

Request and transport events

Event	Payload
`cart:request`	`{ endpoint, method, payload? }`
`cart:response`	`{ endpoint, method, cart }`
`cart:error`	`{ endpoint, method, error }`
`cart:fetch:request`	`{ url, method, init? }`
`cart:fetch:response`	`{ url, method, status, data }`
`cart:fetch:error`	`{ url, method, error }`

The three cart:fetch:* events are off by default. A comment in the interceptor explains that other apps send enough cart requests to make these events noise. Turn them on only while debugging.

UI events

Event	Payload	Direction
`mini-cart:ui:open`	none	Ask the drawer to open
`mini-cart:ui:close`	none	Ask the drawer to close
`mini-cart:ui:update`	`{ action }`	Ask for an arbitrary UI action
`mini-cart:ui:opened`	none	The drawer has opened
`mini-cart:ui:closed`	none	The drawer has closed

open and close are requests. opened and closed report what happened. To react to the drawer, listen for opened and closed.

Readiness

Event	Payload
`mini-cart:ready`	none

The mini-cart emits this once its core has initialised. Code that needs the mini-cart should wait for this event and not assume the mini-cart exists at DOMContentLoaded.

Custom elements

Tag	File
`mini-cart`	`elements/mini-cart.ts`
`mini-cart-header`	`elements/mini-cart-header.ts`
`mini-cart-line-items`	`elements/mini-cart-line-items.ts`
`mini-cart-footer`	`elements/mini-cart-footer.ts`
`mini-cart-summary`	`elements/mini-cart-summary.ts`
`mini-cart-progress-bar`	`elements/mini-cart-progress-bar.ts`
`mini-cart-recommendations`	`elements/mini-cart-recommendations.ts`
`mini-cart-gifts-accordion`	`elements/mini-cart-gifts-accordion.ts`
`mini-cart-discount-code`	`elements/mini-cart-discount-code.ts`
`mini-cart-clear-cart`	`elements/mini-cart-clear-cart.ts`

All paths are relative to src/entrypoints/mini-cart/.

Four more custom elements exist outside the mini-cart. The homepage redesign defines product-card-form, products-carousel and tabbed-carousels, and the quick add modal defines select-options.

Other globals the mini-cart exposes

Global	Purpose
`window.addCheckoutEventChain(fn)`	Register an async step that runs over the cart at checkout. Returns false when there is no footer element

Cart events

On this page