AJAX cart setup

When a customer adds, removes, or changes the quantity of something in their cart, you usually want the cart and your upsell widgets to update right away — without the page reloading. That is exactly what AJAX cart mode does. This guide is the deep dive on the Cart page section of Settings: what each field means, how to find the right selectors for your theme, how the add-to-cart callback works, and how to fix the most common setup problems.

What AJAX cart mode does

AJAX cart mode lets cart updates happen without a full page reload. When it is on, the app intercepts cart changes and refreshes the cart contents — and any upsell widgets tied to the cart — in place. This keeps the cart subtotal, line items, progress bars, and widgets in sync after every add, remove, or quantity change, so a customer never sees a stale total or a widget that hasn't caught up.

The setting that controls this is Enable AJAX (enableAjaxCart). It is off by default. With it off, the app relies on a normal page reload to show updated cart state, which is the safe choice for themes that already handle their own cart updates (more on that below).

The two required selectors

When Enable AJAX is on, the app needs to know where on the page your theme draws the cart, so it can update those regions in place. You provide that with two CSS selectors. Both are required whenever AJAX is enabled.

These selectors tell the app which parts of the rendered cart page to re-render when something changes. If they point at the wrong elements — or at nothing — the app can't update the cart in place, and you'll see the symptoms described in Edge and complex cases.

How to find the right selectors for your theme

Every theme structures its cart page a little differently, so the safest way to set these is to inspect your live cart template.

Common selectors by theme family

These are good starting points, but always confirm against your own theme since merchants and developers often rename classes:

The add-to-cart callback

Sometimes you want your own JavaScript to run every time a product is added to the cart — to fire an analytics event, open a cart drawer, or show a toast. The app supports this with two settings:

How the callback behaves:

• No <script> tag. Paste plain JavaScript only — do not wrap it in <script>...</script>. The app injects and runs it for you.
• Runs on every add-to-cart. Your code executes each time a product is added to the cart through the app's flow.
• You get an item variable. Inside your callback, a variable named item holds the data for the product that was just added. Use it to read the product's details for analytics or messaging.

Example callbacks

Fire a custom analytics event with the added product:

// `item` is the product that was just added to the cart
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: 'app_add_to_cart',
  product: item,
});

Show a quick confirmation toast:

const toast = document.createElement('div');
toast.className = 'app-toast';
toast.textContent = 'Added to cart';
document.body.appendChild(toast);
setTimeout(() => toast.remove(), 2500);

Open the theme's cart drawer after an add (selector depends on your theme):

// Many Online Store 2.0 themes expose the drawer as a custom element
document.querySelector('cart-drawer')?.classList.add('active');
document.querySelector('cart-drawer')?.removeAttribute('hidden');

Relationship to Llama Cart

The selectors and AJAX setting apply to your theme's cart page. They matter most when customers use the standard theme cart.

Llama Cart is the app's own AJAX cart drawer. When you enable Llama Cart, it replaces the theme cart with the app's drawer, and the drawer handles its own rendering and updates. In that setup, the theme cart selectors are about your theme's /cart page rather than the Llama Cart drawer itself.

Price formatting in the AJAX-updated cart

When the app re-renders the cart, prices are formatted according to your Price Decimal Scale setting (priceDecimalScale), found in the Global section of Settings. This is worth knowing here because it controls how every price looks in the cart the AJAX flow updates.

This value also syncs to the global app metafield, so storefront widgets read it directly without an extra API call — keeping the AJAX-updated cart and your widgets formatting prices the same way. Full details are in Cart & checkout settings.

Edge and complex cases

Recipe: enable AJAX, set selectors, verify, add a drawer callback

document.querySelector('cart-drawer')?.classList.add('active');

Troubleshooting

Related