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

x-cart-item

Directives and a magic for changing or removing one cart line item with fetch.

Directives and a magic for changing or removing one cart line item with fetch.

Directive / magic
What it does

x-cart-item="{{ forloop.index }}"

The root, on the item's <form> or a wrapper of one. The expression is required: the item's 1-based line number

x-cart-item.wait-error.3000ms

Modifiers pass through to x-async-form: wait-success (default 1000ms) and wait-error

x-cart-item:context

Holds the item state. The root binds it for you

x-cart-item:form

The form element. Sets method="POST". The root binds it for you

$cartItem.quantity

The quantity to submit. Read and write it, or bind it with x-model

$cartItem.isRemoving

true while the quantity is 0

$cartItem.remove()

Sets the quantity to 0 and submits

$cartItem (the rest)

The same API as $asyncForm: state, errorMessage, errorDescription, submitAsync(), reset(), …

Submission goes to /cart/change.js (window.theme.routes.cartChange) with the line key from data-line-key (or the line number without one), the quantity, and the ids of every section marked data-cart-api-section, so the response includes their updated HTML. The cart re-renders without a page reload.

After each response the plugin sets $cartItem.quantity to the quantity the cart really holds. It finds the line by its key, so a removed line keeps quantity 0 when the next line moves into its position. A stockout returns a 422 without that quantity, so the plugin fetches the cart again. The input returns to the available amount.

Before removal, the plugin moves focus to a neighboring item. Otherwise, hiding the focused row would drop keyboard focus to <body>.

On top of the x-async-form events, the plugin dispatches the standard shopify:cart:lines-update event (action 'update', or 'remove' when the quantity hits 0) before the request, with event.promise resolving to the cart and the theme detail, and shopify:cart:error on failure. See Events. Give the element data-line-key="{{ line_item.key }}". The request then targets the line by key, which stays on this line while another request removes an earlier line and shifts the line numbers, and the event can identify the changed line.

Examples

A basic line item

Use x-cart-item with the line number, bind the input to $cartItem.quantity, and submit on input:

{% for item in cart.items %}
  <form x-cart-item="{{ forloop.index }}">
    <input
      type="number"
      name="updates[]"
      value="{{ item.quantity }}"
      x-model.fill.number="$cartItem.quantity"
      @input.debounce.500ms="$cartItem.submitAsync()"
    >
  </form>
{% endfor %}

The debounce collapses fast typing into one request, and a new submission cancels the pending one.

A quantity stepper that saves on change

Use the x-stepper increment and decrement events to submit each step. The cart line item uses its stepper this way:

A remove button

Use $cartItem.remove() on a button and $cartItem.isRemoving to hide the row while the removal runs:

Showing a stockout

Use the wait-error modifier to clear the message automatically. The cart line item shows the server's stock message for three seconds:

The quantity input snaps back to the amount the cart really holds, so it never shows a number the shop cannot sell.

Customizing

The cart line item's layout, badges, and quantity controls are described in Cart. Use x-cart-form to update the note or several updates[] values in one request.

Last updated

Was this helpful?