For the complete documentation index, see llms.txt. This page is also available as Markdown.

x-cart-api-section

A directive that keeps a section in step with the cart: cart requests return the section's HTML, and the section morphs it in.

A directive that keeps a section in step with the cart: cart requests return the section's HTML, and the section morphs it in without a page reload.

Directive / behavior
What it does

x-cart-api-section

The root, on a section's root element or on an element inside one. Sets data-cart-api-section

data-cart-api-section

The marker x-cart-item, x-cart-form, and x-product-form read to send the section's id in the request's sections parameter

shopify:cart:lines-update / shopify:cart:note-update

Awaits event.promise, then morphs this section's HTML from the result's detail.sections

Overlapping requests

Render once, after the last request settles, from the request that started last

shopify:cart:error, a response without this section, a failed latest request

Reloads through $sectionApi.update(), debounced 500ms and batched

The tab becomes visible

Reloads when the browser is idle, so a cart changed in another tab shows up

The directive takes no value and no modifiers. It needs x-section-api, which binds every shopify-section element automatically.

Shopify applies overlapping cart requests in the order they start, whatever order their responses arrive in. The response of the request that started last holds the newest cart, so an earlier response cannot bring back a removed line or drop a just-added one. createCartRequestGroup() in utils holds that rule for code outside Alpine.

Examples

The cart drawer

Put the directive on the section root. Every line item inside submits through x-cart-item, and the drawer morphs from each response:

<div x-cart-api-section>
  {% render 'cart-list' %}
</div>

The header cart button

A section without a cart form follows the cart the same way. The header menu marks itself, so the item count updates after every add, change, and removal:

Two removes in a row

Click remove on a second line before the first request answers. Both rows hide at once, and the drawer renders once, from the second response. The line item hides itself with $cartItem.isRemoving and the directive does the rest:

Customizing

The reload delay and the batched transport are fixed. Call $sectionApi.update() yourself when a section must reload at another moment. See Cart for the sections that use the directive.

Last updated

Was this helpful?