Adding to Cart with Fetch API

1. The Starting Point: A Standard Shopify Product Form

By default, when you use the standard Liquid {% form 'product', product %} tag, Shopify generates an HTML form similar to this:

<form method="post" action="/cart/add">
  <input type="hidden" name="id" value="{{ product.selected_or_first_available_variant.id }}">
  <input type="number" name="quantity" value="1" min="1">
  <button type="submit">Add to Cart</button>
</form>

When the user clicks the "Add to Cart" button, the browser submits this form, leading to a request to /cart/add and a full page reload. Our goal is to intercept this process to create a smoother user experience.

2. Implementing Asynchronous "Add to Cart"

We'll build this feature step-by-step, following a clear and logical process. The video below provides an excellent walkthrough of this entire process using plain JavaScript, which we will use as our guide.

Step 1: Intercept the Form Submission

Our first task is to prevent the browser's default form submission behavior. We'll use JavaScript to listen for the submit event on our product form and stop it in its tracks.

As the video demonstrates, the core logic is:

1. Select all relevant forms: Using an attribute selector like form[action$="/cart/add"] is a robust way to find all "add to cart" forms, whether on a product page or a collection grid.
2. Loop and attach an event listener: We iterate through each form and listen for the submit event.
3. Prevent the default action: Inside the event handler, we call event.preventDefault(). This gives us a "clean slate" to handle the submission with our own code.

Step 2: Send Form Data Using the Fetch API

Now that we've stopped the default submission, we need to manually send the product data to Shopify's Ajax API. The designated endpoint for this is /cart/add.js.

Let's see how to construct this request.

The key to this step is packaging the form's data. The Shopify Cart API documentation outlines two primary ways to do this.

As you've seen, you can either construct a JSON object or serialize the form with FormData. For theme development, using FormData is the superior approach. Why?

• Extensibility: It automatically includes all input fields within the form. If a Shopify App adds a hidden input for custom properties or other functionality, your code doesn't need to change. It will be included automatically.
• Simplicity: It's less code to write and maintain than manually grabbing each value and building a JSON object.

Your curiosity for "first principles" makes it worthwhile to hear another developer advocate for this approach.

Step 3: Update the UI with the New Cart State

After our fetch request successfully adds the item, the cart has changed on Shopify's servers, but our user's browser doesn't know it yet. We need to provide immediate feedback. The most common updates are refreshing the cart item count and displaying a success message.

A robust pattern for this is to make a second API call to GET /cart.json. This retrieves the entire, up-to-date cart object, ensuring we have the correct total item count, regardless of what was just added.

This sequence—POSTing to add, then GETting to update—is a reliable pattern for dynamic cart interactions.

3. Putting It All Together: The Complete Script

Here is a complete JavaScript snippet that combines all the steps we've covered. You would typically place this in one of your theme's JavaScript asset files.

// Listen for the DOM to be fully loaded before running the script
document.addEventListener('DOMContentLoaded', function() {
  // Select all forms with the action '/cart/add'
  const addToCartForms = document.querySelectorAll('form[action$="/cart/add"]');
  
  addToCartForms.forEach(form => {
    form.addEventListener('submit', async (event) => {
      // 1. Prevent the default form submission (page reload)
      event.preventDefault();

      // You can add a 'loading' state to your button here if you wish
      // e.g., button.classList.add('loading');

      try {
        // 2. Send the form data to the Ajax API
        await fetch('/cart/add.js', {
          method: 'POST',
          body: new FormData(form)
        });

        // 3. Fetch the updated cart data
        const res = await fetch('/cart.json');
        const cart = await res.json();

        // 4. Update UI elements with the new cart state
        // Update all elements with a specific class for the cart count
        document.querySelectorAll('.cart-count').forEach(el => {
          el.textContent = cart.item_count;
        });

        // Display a success message
        // This could be toggling a class on an existing element...
        const successMessage = form.querySelector('.added-to-cart-message');
        if (successMessage) {
          successMessage.classList.add('active');
          // Optionally hide it after a few seconds
          setTimeout(() => { 
            successMessage.classList.remove('active'); 
          }, 3000);
        }
        
      } catch (error) {
        console.error('Error adding to cart:', error);
        // You would add user-facing error handling here
      } finally {
        // Remove the 'loading' state from your button
        // e.g., button.classList.remove('loading');
      }
    });
  });
});

Conclusion

Congratulations! You have just implemented one of the most fundamental features of a modern Shopify theme. By moving from a page reload to an asynchronous request, you've significantly improved the user experience.

Key Takeaways:

• Intercept and Prevent: The process begins by capturing the form's submit event and using event.preventDefault() to stop the browser's default behavior.
• Serialize with FormData: Using new FormData(formElement) is the most robust and future-proof way to gather all the necessary data to send to Shopify.
• Use the Ajax API Endpoints: You make a POST request to /cart/add.js to add an item, and a GET request to /cart.json to retrieve the updated cart state.
• Update the UI: After a successful response, you must use JavaScript to update relevant parts of the page, like the cart item count, to reflect the new state.

In our next lesson, we will build directly on this foundation. Now that we can add items to the cart, we'll learn how to update cart quantities and remove items from a cart drawer using the Ajax API, further enhancing the dynamic capabilities of our theme.