WooCommerce Cart Fragments

Cart Fragments is a WooCommerce JavaScript feature (wc-cart-fragments) that keeps cart-related UI (mini-cart contents, item count, totals) in sync across pages. It sends an AJAX call (wc-ajax=get_refreshed_fragments) and swaps HTML “fragments” returned by the server into the page.

Why it exists

Full-page caching breaks dynamic elements like a header mini-cart. Cart Fragments ensures customers always see the current cart state without forcing page reloads.

How it works (high level)

  • On page load and after “Add to cart,” the script checks a stored cart hash.
  • If needed, it calls /?wc-ajax=get_refreshed_fragments.
  • The server returns { fragments: { selector: html }, cart_hash }.
  • The script replaces matching DOM nodes and triggers events like wc_fragments_loaded and wc_fragments_refreshed.

Common issues

  • Extra request per session/visit: Can degrade performance scores, especially on mobile or slow servers.
  • Unnecessary on sites without a mini-cart: You pay the cost without any visible benefit.
  • Conflicts with custom headers/builders: If you disable it incorrectly, the cart badge/mini-cart may stop updating.

When to keep it enabled

  • You use a mini-cart or cart count badge that must update instantly.
  • You rely on dynamic pricing/content that needs real-time refresh after adding to cart.

When you can disable or limit it

  • No mini-cart or cart badge in the header.
  • Marketing/landing pages where cart UI isn’t shown.
  • You’ve built a custom, lightweight updater (see example below).

Practical optimizations

1) Dequeue on pages that don’t need it

add_action('wp_enqueue_scripts', function () {
    // Keep on cart/checkout; remove elsewhere if you don't show a mini-cart
    if ( ! is_cart() && ! is_checkout() ) {
        wp_dequeue_script('wc-cart-fragments');
        wp_deregister_script('wc-cart-fragments');
    }
}, 20);

2) Only load for visitors who have items in the cart

(Best for sites with heavy caching and no header mini-cart when cart is empty.)

add_action('wp_enqueue_scripts', function () {
    $has_items = ! empty(WC()->cart) && WC()->cart->get_cart_contents_count() > 0;

    if ( ! $has_items && ! is_cart() && ! is_checkout() ) {
        wp_dequeue_script('wc-cart-fragments');
        wp_deregister_script('wc-cart-fragments');
    }
}, 20);

Note: On aggressively cached pages, detecting cart state in PHP can be unreliable. Consider a cookie check (woocommerce_items_in_cart) or a JS gate.

3) Replace with a lightweight cart count updater

If you only need a badge count, listen for Woo events and update a small endpoint yourself.

jQuery(function($){
  // After add to cart, refresh just the counter
  $(document.body).on('added_to_cart', function(){
    fetch('/?wc-ajax=get_refreshed_fragments', { method: 'POST' })
      .then(r => r.json())
      .then(data => {
        // Example: update a simple count element
        if (data && data.cart_hash) {
          // Many themes expose a fragment for count; or expose your own endpoint.
          // Update your #cart-count element as needed.
          document.querySelector('#cart-count')?.dispatchEvent(new Event('cart:refresh')); 
        }
      });
  });
});

Developer notes

  • Script handle: wc-cart-fragments
  • AJAX endpoint: /?wc-ajax=get_refreshed_fragments
  • Key JS events: added_to_cart, wc_fragments_loaded, wc_fragments_refreshed
  • Typical fragment selectors include mini-cart containers and totals areas.

Best practices

  • Audit where cart UI appears; load fragments only there.
  • Pair with server/object caching; avoid running the AJAX on every page where it’s not needed.
  • For builders (Elementor, Divi, block themes), confirm their mini-cart widgets rely on fragments before dequeueing.
  • Test both guest and logged-in flows, and mobile networks.