DEV Community: Eiji Saito

How to Build a Cart Upsell Widget for Shopify with the Ajax Cart API

Eiji Saito — Wed, 26 Aug 2026 06:59:50 +0000

Introduction
What We'll Build
How Cart Upsell Widgets Work
Setting Up the Theme App Extension
Fetching Cart Data and Recommended Products
Building the Liquid Template
Styling the Upsell Widget
Adding Products to the Cart from the Widget
Complete File
Tips and Common Pitfalls
Conclusion
References

Introduction

The cart page is one of the highest-intent moments in the entire shopping journey — the customer has already decided to buy something. It's also one of the most underused spots for merchandising. A well-placed cart upsell widget that recommends relevant products based on what's already in the cart can meaningfully lift average order value (AOV) without adding any friction to checkout.

Unlike product-page recommendations, which Shopify exposes directly through the recommendations Liquid object, there's no built-in Liquid object for "recommend something based on my cart contents." The cart template doesn't have access to product recommendation data at render time, because the cart's contents are dynamic and change without a full page reload (adding, removing, or updating quantities all happen via Ajax in modern themes).

That means a cart upsell widget has to be built client-side: read the current cart with the Cart Ajax API, ask Shopify's Product Recommendations API for related products, filter out anything already in the cart, and render the result. In this tutorial, I'll walk through building exactly that as a Theme App Extension, with full support for adding a recommended product straight from the widget.

What We'll Build

The cart upsell widget will:

Read the current cart contents via /cart.js whenever it loads or the cart changes
Fetch product recommendations from Shopify's Product Recommendations API, based on the most recently added item
Exclude products already in the cart so we never recommend something the customer already has
Render product cards with image, title, price, and an "Add" button
Add the recommended product to the cart via /cart/add.js without a page reload
Automatically refresh after an item is added, so the widget stays in sync with the cart
Be fully configurable from the theme editor (heading text, number of products, colors)
Work on both the cart page and cart drawer, since both are just sections in Online Store 2.0 themes

How Cart Upsell Widgets Work

Before writing code, it's worth understanding the two Shopify APIs this widget leans on, and why we need both.

Product Recommendations API

Shopify exposes a public JSON endpoint at /recommendations/products.json that returns products related to a given product_id. This is the same recommendation engine that powers the recommendations Liquid object on product pages — the difference is that this JSON endpoint can be called from anywhere, including the cart page, via a simple fetch() call. It accepts an intent parameter (related or complementary) and a limit parameter for how many products to return.

The catch: it only accepts a single product_id. It has no concept of "recommend based on these five cart items." So we need to pick one product from the cart to use as the reference — in this tutorial, we'll use the most recently added item.

Cart Ajax API

To know what's in the cart (and to add new items to it), we use Shopify's Cart Ajax API:

GET /cart.js — returns the current cart as JSON, including every line item's product_id, variant_id, and quantity
POST /cart/add.js — adds a variant to the cart and returns the added line item as JSON

Both are same-origin endpoints on the storefront domain, so no CORS configuration or authentication is needed — a plain fetch() works.

Putting It Together

The flow for our widget looks like this:

On load, fetch /cart.js to see what's in the cart
If the cart is empty, hide the widget entirely
Take the most recently added item's product_id as the reference product
Call /recommendations/products.json?product_id=<id> to get related products
Filter out any recommended product that's already a line item in the cart
Render the remaining products as cards with an "Add" button
When "Add" is clicked, POST to /cart/add.js, then re-run the whole flow so the widget updates itself

Setting Up the Theme App Extension

Prerequisites

Make sure you have:

A Shopify Partner account
A development store
Shopify CLI installed
An existing Shopify app (or create one with shopify app init)

Generate the Extension

Inside your app directory, run:

shopify app generate extension --template theme_app_extension --name cart-upsell

This creates the following structure:

extensions/
  cart-upsell/
    blocks/
    assets/
    locales/
    snippets/

We'll create two files:

blocks/cart-upsell.liquid — the app block with markup, JavaScript, and schema
assets/cart-upsell.css — styles for the widget

Because this block targets the cart template, merchants will be able to add it from the theme editor to any section on the cart page that supports app blocks (in Dawn-based themes, that's typically main-cart-items or the cart drawer section).

Fetching Cart Data and Recommended Products

Let's build the data-fetching logic first, since it's the core of the widget.

Reading the Cart

function fetchCart() {
  return fetch('/cart.js').then((res) => res.json());
}

/cart.js returns an object with an items array. Each item has product_id, variant_id, quantity, and pricing fields (in cents). We only need product_id here — first to pick a reference product, and second to build a list of products to exclude from the recommendations.

Picking a Reference Product

function getReferenceProductId(cart) {
  if (!cart.items.length) return null;
  return cart.items[cart.items.length - 1].product_id;
}

Shopify appends newly added variants to the end of the items array (as long as it's a genuinely new line item rather than a quantity bump on an existing one), so the last item is a reasonable proxy for "what did the customer just add." It's not perfect — but for a recommendation seed, "the most recent addition" is a solid heuristic that requires no extra state tracking.

Fetching Recommendations

function fetchRecommendations(productId, count) {
  const url = `/recommendations/products.json?product_id=${productId}&limit=${count}&intent=related`;
  return fetch(url).then((res) => res.json());
}

We request more products than we actually plan to display (count = limit + number of items already in cart), because some of the returned recommendations will likely already be in the cart and need to be filtered out. Requesting extra up front avoids a second round-trip if the first few results get filtered away.

Filtering and Limiting

function getUpsellProducts(cart, recommendationsData, limit) {
  const excludeIds = cart.items.map((item) => item.product_id);

  return (recommendationsData.products || [])
    .filter((product) => product.available)
    .filter((product) => !excludeIds.includes(product.id))
    .slice(0, limit);
}

Two filters matter here: product.available drops out-of-stock products (recommending something the customer can't buy is worse than recommending nothing), and the excludeIds check drops anything already sitting in the cart.

Building the Liquid Template

Create the app block file at extensions/cart-upsell/blocks/cart-upsell.liquid.

The Liquid side of this widget is intentionally minimal — almost all of the logic runs client-side in JavaScript, since the cart's contents aren't known until the browser loads the page. Liquid's job here is just to render the container, pass merchant settings through as data attributes and CSS custom properties, and output the shop's money format so our JavaScript can display prices correctly.

{{ 'cart-upsell.css' | asset_url | stylesheet_tag }}

<div
  id="cart-upsell"
  class="cart-upsell"
  data-limit="{{ block.settings.product_limit }}"
  data-money-format="{{ shop.money_format | escape }}"
  style="
    --cart-upsell-bg: {{ block.settings.background_color }};
    --cart-upsell-text: {{ block.settings.text_color }};
    --cart-upsell-btn-bg: {{ block.settings.button_color }};
    --cart-upsell-btn-text: {{ block.settings.button_text_color }};
  "
  hidden
>
  <h3 class="cart-upsell__heading">{{ block.settings.heading }}</h3>
  <div class="cart-upsell__list" id="cart-upsell-list"></div>
</div>

A few things worth calling out:

hidden by default — the widget starts hidden and JavaScript reveals it only once it has products to show. This avoids a flash of an empty heading before the cart data loads.
data-money-format — we pass shop.money_format through as a data attribute rather than hardcoding a currency symbol, so prices render correctly regardless of the store's currency and formatting conventions.
CSS custom properties — merchant-configurable colors are passed as inline custom properties, keeping all visual styling in the CSS file rather than generating Liquid-conditional CSS.

Schema

{% schema %}
{
  "name": "Cart Upsell",
  "target": "section",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Heading",
      "default": "You might also like"
    },
    {
      "type": "range",
      "id": "product_limit",
      "label": "Number of products to show",
      "min": 2,
      "max": 6,
      "step": 1,
      "default": 4
    },
    {
      "type": "color",
      "id": "background_color",
      "label": "Background color",
      "default": "#f7f7f7"
    },
    {
      "type": "color",
      "id": "text_color",
      "label": "Text color",
      "default": "#333333"
    },
    {
      "type": "color",
      "id": "button_color",
      "label": "Button color",
      "default": "#333333"
    },
    {
      "type": "color",
      "id": "button_text_color",
      "label": "Button text color",
      "default": "#ffffff"
    }
  ],
  "templates": ["cart"]
}
{% endschema %}

The "templates": ["cart"] entry is what makes this block selectable from sections on the cart template in the theme editor — without it, the block would be available everywhere, which doesn't make sense for a widget that depends on cart state.

Styling the Upsell Widget

Create the stylesheet at extensions/cart-upsell/assets/cart-upsell.css.

The widget renders as a responsive grid of product cards. On wider screens it shows multiple columns; on mobile it collapses to a horizontally scrollable row, which is a common pattern for secondary merchandising so it doesn't push the actual cart contents and checkout button too far down the page.

.cart-upsell {
  background-color: var(--cart-upsell-bg, #f7f7f7);
  color: var(--cart-upsell-text, #333333);
  padding: 20px;
  border-radius: 8px;
  margin-top: 20px;
}

.cart-upsell__heading {
  margin: 0 0 14px;
  font-size: 16px;
  font-weight: 700;
  color: var(--cart-upsell-text, #333333);
}

.cart-upsell__list {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
  gap: 14px;
}

.cart-upsell__card {
  display: flex;
  flex-direction: column;
  background-color: #ffffff;
  border-radius: 6px;
  overflow: hidden;
  border: 1px solid rgba(0, 0, 0, 0.08);
}

.cart-upsell__image-link {
  display: block;
  aspect-ratio: 1 / 1;
  background-color: #f0f0f0;
}

.cart-upsell__image-link img {
  width: 100%;
  height: 100%;
  object-fit: cover;
  display: block;
}

.cart-upsell__info {
  display: flex;
  flex-direction: column;
  gap: 6px;
  padding: 10px;
}

.cart-upsell__title {
  font-size: 13px;
  font-weight: 600;
  color: var(--cart-upsell-text, #333333);
  text-decoration: none;
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

.cart-upsell__title:hover {
  text-decoration: underline;
}

.cart-upsell__price {
  font-size: 13px;
  font-weight: 700;
}

.cart-upsell__add-btn {
  margin-top: auto;
  padding: 8px 10px;
  border: none;
  border-radius: 4px;
  font-size: 12px;
  font-weight: 600;
  cursor: pointer;
  background-color: var(--cart-upsell-btn-bg, #333333);
  color: var(--cart-upsell-btn-text, #ffffff);
  transition: opacity 0.2s ease;
}

.cart-upsell__add-btn:hover {
  opacity: 0.85;
}

.cart-upsell__add-btn:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

/* Mobile: horizontally scrollable row instead of a grid */
@media (max-width: 600px) {
  .cart-upsell__list {
    display: flex;
    overflow-x: auto;
    scroll-snap-type: x mandatory;
    gap: 10px;
    padding-bottom: 4px;
  }

  .cart-upsell__card {
    flex: 0 0 120px;
    scroll-snap-align: start;
  }
}

A couple of details worth explaining:

aspect-ratio: 1 / 1 on the image link reserves space for the image before it loads, preventing layout shift as recommendations render asynchronously.
-webkit-line-clamp: 2 truncates long product titles to two lines instead of letting them overflow the card or push the price and button down inconsistently between cards.
margin-top: auto on the button pins it to the bottom of the card even when titles wrap to different heights, keeping all "Add" buttons aligned in a row.

Adding Products to the Cart from the Widget

Now let's wire up the rendering and add-to-cart logic. Add this <script> block to cart-upsell.liquid, after the container <div>:

<script>
  (function () {
    const widget = document.getElementById('cart-upsell');
    if (!widget) return;

    const list = document.getElementById('cart-upsell-list');
    const limit = parseInt(widget.dataset.limit, 10) || 4;
    const moneyFormat = widget.dataset.moneyFormat || '${{amount}}';

    function formatMoney(cents, format) {
      const placeholderRegex = /\{\{\s*(\w+)\s*\}\}/;
      const match = format.match(placeholderRegex);
      if (!match) return '$' + (cents / 100).toFixed(2);

      function withDelimiters(number, precision, thousands, decimalSep) {
        const fixed = (number / 100).toFixed(precision);
        const parts = fixed.split('.');
        const dollars = parts[0].replace(/(\d)(?=(\d{3})+(?!\d))/g, '$1' + thousands);
        const cents = parts[1] ? decimalSep + parts[1] : '';
        return dollars + cents;
      }

      let value;
      switch (match[1]) {
        case 'amount_no_decimals':
          value = withDelimiters(cents, 0, ',', '.');
          break;
        case 'amount_with_comma_separator':
          value = withDelimiters(cents, 2, '.', ',');
          break;
        case 'amount_no_decimals_with_comma_separator':
          value = withDelimiters(cents, 0, '.', ',');
          break;
        default:
          value = withDelimiters(cents, 2, ',', '.');
      }

      return format.replace(placeholderRegex, value);
    }

    function thumbnail(src) {
      if (!src) return null;
      return src + (src.includes('?') ? '&' : '?') + 'width=200';
    }

    function fetchCart() {
      return fetch('/cart.js').then((res) => res.json());
    }

    function fetchRecommendations(productId, count) {
      const url = `/recommendations/products.json?product_id=${productId}&limit=${count}&intent=related`;
      return fetch(url).then((res) => res.json());
    }

    function getReferenceProductId(cart) {
      if (!cart.items.length) return null;
      return cart.items[cart.items.length - 1].product_id;
    }

    function buildCard(product) {
      const variant = product.variants.find((v) => v.available) || product.variants[0];
      const priceCents = Math.round(parseFloat(variant.price) * 100);

      const card = document.createElement('div');
      card.className = 'cart-upsell__card';

      const imageLink = document.createElement('a');
      imageLink.href = product.url;
      imageLink.className = 'cart-upsell__image-link';

      const thumbSrc = product.images && product.images[0] ? thumbnail(product.images[0].src) : null;
      if (thumbSrc) {
        const img = document.createElement('img');
        img.src = thumbSrc;
        img.alt = product.title;
        img.loading = 'lazy';
        img.width = 140;
        img.height = 140;
        imageLink.appendChild(img);
      }

      const info = document.createElement('div');
      info.className = 'cart-upsell__info';

      const title = document.createElement('a');
      title.href = product.url;
      title.className = 'cart-upsell__title';
      title.textContent = product.title;

      const price = document.createElement('div');
      price.className = 'cart-upsell__price';
      price.textContent = formatMoney(priceCents, moneyFormat);

      const button = document.createElement('button');
      button.type = 'button';
      button.className = 'cart-upsell__add-btn';
      button.textContent = 'Add';
      button.disabled = !variant.available;
      button.addEventListener('click', function () {
        addToCart(variant.id, button);
      });

      info.appendChild(title);
      info.appendChild(price);
      info.appendChild(button);
      card.appendChild(imageLink);
      card.appendChild(info);

      return card;
    }

    function renderProducts(products) {
      list.innerHTML = '';

      if (!products.length) {
        widget.hidden = true;
        return;
      }

      products.forEach(function (product) {
        list.appendChild(buildCard(product));
      });

      widget.hidden = false;
    }

    function addToCart(variantId, button) {
      const originalText = button.textContent;
      button.disabled = true;
      button.textContent = 'Adding...';

      fetch('/cart/add.js', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ items: [{ id: variantId, quantity: 1 }] }),
      })
        .then(function (response) {
          if (!response.ok) throw new Error('Add to cart failed');
          return response.json();
        })
        .then(function () {
          button.textContent = 'Added!';
          document.dispatchEvent(new CustomEvent('cart:updated', { bubbles: true }));
          init();
        })
        .catch(function (error) {
          console.error('Cart upsell error:', error);
          button.disabled = false;
          button.textContent = originalText;
        });
    }

    function init() {
      fetchCart().then(function (cart) {
        const referenceId = getReferenceProductId(cart);

        if (!referenceId) {
          widget.hidden = true;
          return;
        }

        const excludeIds = cart.items.map(function (item) {
          return item.product_id;
        });
        const fetchCount = limit + excludeIds.length;

        fetchRecommendations(referenceId, fetchCount).then(function (data) {
          const products = (data.products || [])
            .filter(function (product) {
              return product.available;
            })
            .filter(function (product) {
              return excludeIds.indexOf(product.id) === -1;
            })
            .slice(0, limit);

          renderProducts(products);
        });
      });
    }

    document.addEventListener('cart:updated', init);
    document.addEventListener('cart:refresh', init);
    window.CartUpsell = { refresh: init };

    init();
  })();
</script>

Walking through the key parts:

formatMoney() — a small, self-contained implementation of Shopify's standard money formatting logic. It reads the {{amount}}-style placeholder from shop.money_format and applies the right decimal and thousands separators. We need our own copy because recommendation data isn't run through Liquid's money filter — it arrives as raw JSON — and not every theme exposes Shopify.formatMoney globally.

thumbnail() — appends a width query parameter to the Shopify CDN image URL. Shopify's CDN resizes images on the fly based on this parameter, so we avoid downloading full-resolution product images just to show a 140px thumbnail.

addToCart() — posts the selected variant to /cart/add.js, then dispatches a cart:updated custom event (the same convention used by many themes, including Dawn, to refresh cart drawers and cart icon counts) and calls init() again so the widget re-fetches the cart and recommendations — the product that was just added disappears from the list automatically because it's now in excludeIds.

Event listeners on cart:updated / cart:refresh — these let the widget refresh itself when the cart changes from outside the widget too, e.g. when the customer updates a quantity or removes a line item elsewhere on the cart page. Since not every theme dispatches these events consistently, we also expose window.CartUpsell.refresh() as an escape hatch — see the Tips section below.

Complete File

Here's the complete cart-upsell.liquid file — everything in one place so you can copy it directly into your project:

extensions/cart-upsell/blocks/cart-upsell.liquid

{{ 'cart-upsell.css' | asset_url | stylesheet_tag }}

<div
  id="cart-upsell"
  class="cart-upsell"
  data-limit="{{ block.settings.product_limit }}"
  data-money-format="{{ shop.money_format | escape }}"
  style="
    --cart-upsell-bg: {{ block.settings.background_color }};
    --cart-upsell-text: {{ block.settings.text_color }};
    --cart-upsell-btn-bg: {{ block.settings.button_color }};
    --cart-upsell-btn-text: {{ block.settings.button_text_color }};
  "
  hidden
>
  <h3 class="cart-upsell__heading">{{ block.settings.heading }}</h3>
  <div class="cart-upsell__list" id="cart-upsell-list"></div>
</div>

<script>
  (function () {
    const widget = document.getElementById('cart-upsell');
    if (!widget) return;

    const list = document.getElementById('cart-upsell-list');
    const limit = parseInt(widget.dataset.limit, 10) || 4;
    const moneyFormat = widget.dataset.moneyFormat || '${{amount}}';

    function formatMoney(cents, format) {
      const placeholderRegex = /\{\{\s*(\w+)\s*\}\}/;
      const match = format.match(placeholderRegex);
      if (!match) return '$' + (cents / 100).toFixed(2);

      function withDelimiters(number, precision, thousands, decimalSep) {
        const fixed = (number / 100).toFixed(precision);
        const parts = fixed.split('.');
        const dollars = parts[0].replace(/(\d)(?=(\d{3})+(?!\d))/g, '$1' + thousands);
        const cents = parts[1] ? decimalSep + parts[1] : '';
        return dollars + cents;
      }

      let value;
      switch (match[1]) {
        case 'amount_no_decimals':
          value = withDelimiters(cents, 0, ',', '.');
          break;
        case 'amount_with_comma_separator':
          value = withDelimiters(cents, 2, '.', ',');
          break;
        case 'amount_no_decimals_with_comma_separator':
          value = withDelimiters(cents, 0, '.', ',');
          break;
        default:
          value = withDelimiters(cents, 2, ',', '.');
      }

      return format.replace(placeholderRegex, value);
    }

    function thumbnail(src) {
      if (!src) return null;
      return src + (src.includes('?') ? '&' : '?') + 'width=200';
    }

    function fetchCart() {
      return fetch('/cart.js').then((res) => res.json());
    }

    function fetchRecommendations(productId, count) {
      const url = `/recommendations/products.json?product_id=${productId}&limit=${count}&intent=related`;
      return fetch(url).then((res) => res.json());
    }

    function getReferenceProductId(cart) {
      if (!cart.items.length) return null;
      return cart.items[cart.items.length - 1].product_id;
    }

    function buildCard(product) {
      const variant = product.variants.find((v) => v.available) || product.variants[0];
      const priceCents = Math.round(parseFloat(variant.price) * 100);

      const card = document.createElement('div');
      card.className = 'cart-upsell__card';

      const imageLink = document.createElement('a');
      imageLink.href = product.url;
      imageLink.className = 'cart-upsell__image-link';

      const thumbSrc = product.images && product.images[0] ? thumbnail(product.images[0].src) : null;
      if (thumbSrc) {
        const img = document.createElement('img');
        img.src = thumbSrc;
        img.alt = product.title;
        img.loading = 'lazy';
        img.width = 140;
        img.height = 140;
        imageLink.appendChild(img);
      }

      const info = document.createElement('div');
      info.className = 'cart-upsell__info';

      const title = document.createElement('a');
      title.href = product.url;
      title.className = 'cart-upsell__title';
      title.textContent = product.title;

      const price = document.createElement('div');
      price.className = 'cart-upsell__price';
      price.textContent = formatMoney(priceCents, moneyFormat);

      const button = document.createElement('button');
      button.type = 'button';
      button.className = 'cart-upsell__add-btn';
      button.textContent = 'Add';
      button.disabled = !variant.available;
      button.addEventListener('click', function () {
        addToCart(variant.id, button);
      });

      info.appendChild(title);
      info.appendChild(price);
      info.appendChild(button);
      card.appendChild(imageLink);
      card.appendChild(info);

      return card;
    }

    function renderProducts(products) {
      list.innerHTML = '';

      if (!products.length) {
        widget.hidden = true;
        return;
      }

      products.forEach(function (product) {
        list.appendChild(buildCard(product));
      });

      widget.hidden = false;
    }

    function addToCart(variantId, button) {
      const originalText = button.textContent;
      button.disabled = true;
      button.textContent = 'Adding...';

      fetch('/cart/add.js', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ items: [{ id: variantId, quantity: 1 }] }),
      })
        .then(function (response) {
          if (!response.ok) throw new Error('Add to cart failed');
          return response.json();
        })
        .then(function () {
          button.textContent = 'Added!';
          document.dispatchEvent(new CustomEvent('cart:updated', { bubbles: true }));
          init();
        })
        .catch(function (error) {
          console.error('Cart upsell error:', error);
          button.disabled = false;
          button.textContent = originalText;
        });
    }

    function init() {
      fetchCart().then(function (cart) {
        const referenceId = getReferenceProductId(cart);

        if (!referenceId) {
          widget.hidden = true;
          return;
        }

        const excludeIds = cart.items.map(function (item) {
          return item.product_id;
        });
        const fetchCount = limit + excludeIds.length;

        fetchRecommendations(referenceId, fetchCount).then(function (data) {
          const products = (data.products || [])
            .filter(function (product) {
              return product.available;
            })
            .filter(function (product) {
              return excludeIds.indexOf(product.id) === -1;
            })
            .slice(0, limit);

          renderProducts(products);
        });
      });
    }

    document.addEventListener('cart:updated', init);
    document.addEventListener('cart:refresh', init);
    window.CartUpsell = { refresh: init };

    init();
  })();
</script>

{% schema %}
{
  "name": "Cart Upsell",
  "target": "section",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Heading",
      "default": "You might also like"
    },
    {
      "type": "range",
      "id": "product_limit",
      "label": "Number of products to show",
      "min": 2,
      "max": 6,
      "step": 1,
      "default": 4
    },
    {
      "type": "color",
      "id": "background_color",
      "label": "Background color",
      "default": "#f7f7f7"
    },
    {
      "type": "color",
      "id": "text_color",
      "label": "Text color",
      "default": "#333333"
    },
    {
      "type": "color",
      "id": "button_color",
      "label": "Button color",
      "default": "#333333"
    },
    {
      "type": "color",
      "id": "button_text_color",
      "label": "Button text color",
      "default": "#ffffff"
    }
  ],
  "templates": ["cart"]
}
{% endschema %}

extensions/cart-upsell/assets/cart-upsell.css

.cart-upsell {
  background-color: var(--cart-upsell-bg, #f7f7f7);
  color: var(--cart-upsell-text, #333333);
  padding: 20px;
  border-radius: 8px;
  margin-top: 20px;
}

.cart-upsell__heading {
  margin: 0 0 14px;
  font-size: 16px;
  font-weight: 700;
  color: var(--cart-upsell-text, #333333);
}

.cart-upsell__list {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
  gap: 14px;
}

.cart-upsell__card {
  display: flex;
  flex-direction: column;
  background-color: #ffffff;
  border-radius: 6px;
  overflow: hidden;
  border: 1px solid rgba(0, 0, 0, 0.08);
}

.cart-upsell__image-link {
  display: block;
  aspect-ratio: 1 / 1;
  background-color: #f0f0f0;
}

.cart-upsell__image-link img {
  width: 100%;
  height: 100%;
  object-fit: cover;
  display: block;
}

.cart-upsell__info {
  display: flex;
  flex-direction: column;
  gap: 6px;
  padding: 10px;
}

.cart-upsell__title {
  font-size: 13px;
  font-weight: 600;
  color: var(--cart-upsell-text, #333333);
  text-decoration: none;
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

.cart-upsell__title:hover {
  text-decoration: underline;
}

.cart-upsell__price {
  font-size: 13px;
  font-weight: 700;
}

.cart-upsell__add-btn {
  margin-top: auto;
  padding: 8px 10px;
  border: none;
  border-radius: 4px;
  font-size: 12px;
  font-weight: 600;
  cursor: pointer;
  background-color: var(--cart-upsell-btn-bg, #333333);
  color: var(--cart-upsell-btn-text, #ffffff);
  transition: opacity 0.2s ease;
}

.cart-upsell__add-btn:hover {
  opacity: 0.85;
}

.cart-upsell__add-btn:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

@media (max-width: 600px) {
  .cart-upsell__list {
    display: flex;
    overflow-x: auto;
    scroll-snap-type: x mandatory;
    gap: 10px;
    padding-bottom: 4px;
  }

  .cart-upsell__card {
    flex: 0 0 120px;
    scroll-snap-align: start;
  }
}

Tips and Common Pitfalls

Recommendations API Prices Are Not in Cents

This one trips up a lot of people the first time: /cart.js returns prices in cents (e.g., 1999 for $19.99), but /recommendations/products.json returns variant prices as decimal strings (e.g., "19.99"), matching the format of the classic /products.json endpoint. Mixing these up will make your prices look 100x too small or force awkward manual conversions. Our buildCard() function explicitly converts with Math.round(parseFloat(variant.price) * 100) before formatting — don't skip that step.

Empty Recommendations Are Normal

If a store hasn't been live long enough to generate purchase-pattern data, or if a product doesn't have manually curated recommendations set up in the Shopify admin, the recommendations endpoint can return an empty products array. Always design for this — our widget hides itself with widget.hidden = true rather than showing an empty "You might also like" heading with nothing under it.

`intent=complementary` Needs Configuration

We used intent=related, which works out of the box using Shopify's automatic recommendation engine. The intent=complementary option (frequently-bought-together style suggestions) relies on recommendation data that's typically configured through the Search & Discovery app or generated from historical order data. If you switch to complementary and get empty results on a fresh dev store, that's expected — it needs real sales data or manual configuration to populate.

Not All Themes Dispatch the Same Cart Events

We listen for cart:updated and cart:refresh to know when to refresh the widget, which covers Dawn and many Dawn-based themes. But cart event naming isn't standardized across all Shopify themes — some use ajaxCart:updated, others don't dispatch any custom event at all when quantities change inline. If your widget isn't refreshing after a quantity change elsewhere on the cart page, inspect the theme's cart scripts for its actual event name, or add a listener for it. The window.CartUpsell.refresh() escape hatch we exposed is there specifically so you can wire up theme-specific events without modifying the extension code.

Debounce If You Add Quantity-Watching

If you extend this widget to also refresh when quantity <input> fields change on the cart page (rather than only after full cart mutations), debounce the fetch calls. Quantity steppers fire input events on every click, and calling /cart.js plus the recommendations endpoint on every keystroke or click is wasteful and can cause the widget to flicker as responses race each other.

Cart Drawer vs. Cart Page Placement

Because this is a Theme App Extension app block, the same file works in both the cart page and a cart drawer, provided the theme's drawer markup is built from sections that accept app blocks (true for Dawn and most modern Online Store 2.0 themes). Test in both contexts — drawers are narrower, so the mobile horizontal-scroll CSS we wrote often ends up being the primary layout even on desktop drawers, not just phone screens.

Conclusion

We've built a cart upsell widget that reads live cart data, asks Shopify's Product Recommendations API for relevant products, filters out what's already in the cart, and lets customers add a recommendation without leaving the cart page. The whole thing runs on two public, unauthenticated Shopify endpoints — no backend, no app proxy, no extra API credentials — which makes it a lightweight addition to any Theme App Extension.

The trickiest parts are the ones that aren't obvious from the API docs alone: the cents-vs-decimal price mismatch between /cart.js and the recommendations endpoint, the inconsistency in cart event names across themes, and designing gracefully for the case where there's simply nothing to recommend. Handle those three things well, and the rest of the implementation is straightforward fetch-and-render.

References

How to Embed YouTube Videos in Shopify Without Killing Your Page Speed

Eiji Saito — Fri, 31 Jul 2026 07:23:02 +0000

Introduction
What We'll Build
Why a Plain YouTube iframe Hurts Your Store
The Facade Pattern Explained
Setting Up the Theme App Extension
Parsing the YouTube URL with Liquid
Building the Facade Markup
Styling a Responsive 16:9 Player
Swapping in the Real iframe with JavaScript
Making It Configurable from the Theme Editor
Complete File
Tips and Common Pitfalls
Conclusion
UR: Smart YouTube Embed
References

Introduction

Product videos sell. A 30-second clip showing how a jacket moves, how a blender handles frozen fruit, or how a piece of furniture gets assembled does more for conversion than three paragraphs of copy. So merchants do the obvious thing: they grab the Embed code from YouTube, paste it into a Shopify page, and move on.

Then the Lighthouse score tanks.

A single default YouTube embed pulls in hundreds of kilobytes of JavaScript before the visitor has clicked anything. Put three of them on a collection page and you've added more weight than the rest of your theme combined. On mobile, where a big chunk of Shopify traffic lives, that's a measurable hit to Largest Contentful Paint and Interaction to Next Paint — the exact metrics Shopify surfaces in the Online Store Speed report.

The fix isn't to drop video. It's to stop loading the player until someone actually wants to watch.

In this tutorial we'll build a YouTube embed block as a Shopify Theme App Extension using the facade pattern: render a lightweight thumbnail with a play button, and only inject the real <iframe> on click. We'll parse any YouTube URL format in Liquid (watch links, short links, Shorts, embed URLs), build a responsive player that never causes layout shift, wire up click-to-load JavaScript that survives the theme editor, and expose everything as theme editor settings so merchants can drop the block anywhere without touching code.

Everything here is production code you can paste into an Online Store 2.0 theme today.

What We'll Build

A YouTube video block that a merchant can add to any section from the theme editor. It will:

Accept any YouTube URL format — youtube.com/watch?v=, youtu.be/, /embed/, /shorts/, or /live/ — and extract the video ID in Liquid
Render zero third-party JavaScript on page load — just one image and a play button
Load the real player on click, with autoplay so the first click is the only click
Stay perfectly responsive at 16:9, 9:16 (Shorts), or 4:3 with no cumulative layout shift
Use youtube-nocookie.com so no tracking cookies are set until playback starts
Support a custom thumbnail uploaded through Shopify's image picker, with an automatic fallback when YouTube has no high-res thumbnail
Be keyboard accessible — a real <button>, real focus states, a real accessible name

The whole thing is three files: one Liquid block, one CSS file, one JS file. No dependencies, no build step, no player library.

Why a Plain YouTube iframe Hurts Your Store

Here's what YouTube's own embed code looks like:

<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/VIDEO_ID"
  title="YouTube video player"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
  allowfullscreen
></iframe>

It works. It's also expensive, for four separate reasons.

1. It downloads the full player before anyone presses play. The embed pulls the YouTube player bundle, its CSS, fonts, and thumbnail assets during initial page load. That's a large amount of render-blocking-adjacent work happening on the main thread for content the visitor may never watch. Multiply by the number of videos on the page.

2. It competes with your own assets. Your product images, your cart drawer script, your theme's JavaScript — they all fight the YouTube player for bandwidth and main-thread time. On a mid-range Android phone over 4G, that contention is exactly what pushes LCP past the 2.5s threshold.

3. It sets cookies immediately. The standard youtube.com embed drops tracking cookies on load, not on play. If you're selling into the EU, that has consent-banner implications before the visitor has interacted with anything.

4. Fixed width and height cause layout shift. width="560" height="315" is not responsive. Merchants who paste this into a rich text field get a video that overflows on mobile, and any CSS that resizes it after paint contributes to CLS.

The important insight: the visitor doesn't need the player until they click play. Everything before that moment is just a picture of a video with a play button on it. And a picture is cheap.

The Facade Pattern Explained

A facade is a lightweight stand-in for a heavy third-party embed. It looks like the real thing, but it's made of static HTML. When the user interacts with it, you replace it with the real embed.

For YouTube, the facade is:

A thumbnail image, which YouTube serves for free at predictable URLs:
- https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg — 1280×720, not available for every video
- https://img.youtube.com/vi/VIDEO_ID/hqdefault.jpg — 480×360, always available
A play button drawn with inline SVG — no image request at all
A click handler that builds the <iframe> with autoplay=1 and swaps it in

The tradeoff is one extra click's worth of latency: the player has to load after the click instead of before it. In practice this is barely noticeable — the player starts streaming in well under a second on a normal connection, and we'll warm up the connection on hover to shave off the DNS and TLS handshake.

What you get in return is a page that ships zero third-party JavaScript unless the visitor asks for it. On a product page with one video, that's typically the difference between a passing and a failing performance audit.

Here's the flow:

Page load          →  <img> + <svg> play button   (~30 KB, cacheable)
User hovers        →  preconnect to YouTube        (DNS + TLS warmed)
User clicks        →  <iframe autoplay=1> injected (player loads, video plays)

Now let's build it.

Setting Up the Theme App Extension

We're building this as a Theme App Extension rather than editing a theme directly. That's the modern approach for Shopify apps: your block lives in your app, merchants add it through the theme editor, and it survives theme updates because you never touch the merchant's theme files.

If you don't have an app yet, create one with the Shopify CLI:

npm init @shopify/app@latest
cd your-app-name

Then generate the extension:

shopify app generate extension --template theme_app_extension --name youtube-embed

You'll get this structure:

extensions/
└── youtube-embed/
    ├── assets/
    ├── blocks/
    ├── locales/
    ├── snippets/
    └── shopify.extension.toml

The three directories that matter here:

blocks/ — Liquid files that merchants can add to sections in the theme editor. Each file is one block. This is where our {% schema %} lives.
assets/ — CSS, JS, and images. Shopify serves these from its CDN.
snippets/ — reusable Liquid partials you can {% render %} from your blocks.

Create three files:

extensions/youtube-embed/
├── assets/
│   ├── youtube-embed.css
│   └── youtube-embed.js
└── blocks/
    └── youtube-embed.liquid

Then start the dev server:

shopify app dev

The CLI gives you a preview URL. Open your development store's theme editor, click Add block inside any section, and your app's block appears under the Apps category. Changes to your extension files hot-reload in the editor.

One thing worth knowing up front: a theme app extension block cannot make network requests to your app's backend on render. It's Liquid, rendered by Shopify, with no server round-trip. Everything the block needs must come from block settings, shop metafields, or client-side JavaScript. For a YouTube embed that's not a limitation at all — a video URL is the only input we need.

Parsing the YouTube URL with Liquid

Merchants will paste whatever URL is in their address bar. That means you need to handle all of these:

https://www.youtube.com/watch?v=dQw4w9WgXcQ
https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=42s
https://youtu.be/dQw4w9WgXcQ
https://youtu.be/dQw4w9WgXcQ?si=AbCdEfGhIjKl
https://www.youtube.com/embed/dQw4w9WgXcQ
https://www.youtube.com/shorts/dQw4w9WgXcQ
https://www.youtube.com/live/dQw4w9WgXcQ
dQw4w9WgXcQ

Liquid has no regex, so we do it with split. The trick is to branch on the URL shape first, then run every result through the same cleanup chain:

{%- liquid
  assign raw_url = block.settings.video_url | strip
  assign video_id = ''

  if raw_url contains 'youtu.be/'
    assign video_id = raw_url | split: 'youtu.be/' | last
  elsif raw_url contains '/embed/'
    assign video_id = raw_url | split: '/embed/' | last
  elsif raw_url contains '/shorts/'
    assign video_id = raw_url | split: '/shorts/' | last
  elsif raw_url contains '/live/'
    assign video_id = raw_url | split: '/live/' | last
  elsif raw_url contains 'v='
    assign video_id = raw_url | split: 'v=' | last
  else
    assign video_id = raw_url
  endif

  assign video_id = video_id | split: '?' | first | split: '&' | first | split: '/' | first | strip
-%}

Walk through what that cleanup chain does:

| Input after branch | split: '?' \| first | split: '&' \| first | split: '/' \| first |
| --------------------- | --------------------- | --------------------- | --------------------- |
| dQw4w9WgXcQ?si=AbCd | dQw4w9WgXcQ | dQw4w9WgXcQ | dQw4w9WgXcQ |
| dQw4w9WgXcQ&t=42s | dQw4w9WgXcQ&t=42s | dQw4w9WgXcQ | dQw4w9WgXcQ |
| dQw4w9WgXcQ/ | dQw4w9WgXcQ | dQw4w9WgXcQ | dQw4w9WgXcQ |

Three filters, every case covered. The else branch means a merchant can also paste a bare video ID and it just works — which they will, so handle it.

Note the branch order matters. /embed/ and /shorts/ are checked before v= because an embed URL like .../embed/ID?rel=0&v=x would otherwise match the wrong branch.

Guarding against an empty URL

Never render broken markup. If there's no video ID, show nothing on the storefront — but show a helpful message inside the theme editor:

{%- if video_id == blank -%}
  {%- if request.design_mode -%}
    <div class="ur-yt__placeholder">
      Add a YouTube URL in the block settings to display a video.
    </div>
  {%- endif -%}
{%- else -%}
  {%- comment -%} video markup goes here {%- endcomment -%}
{%- endif -%}

request.design_mode is true only when the page is being rendered inside the theme editor. It's the right way to give merchants feedback about misconfiguration without leaking developer messaging to customers. Use it liberally.

Building the thumbnail URL

If the merchant uploaded a custom thumbnail, use Shopify's CDN with responsive sizing. Otherwise fall back to YouTube's:

{%- liquid
  assign thumb_fallback = ''

  if block.settings.custom_thumbnail != blank
    assign thumb_src = block.settings.custom_thumbnail | image_url: width: 1280
  else
    assign thumb_src = 'https://img.youtube.com/vi/' | append: video_id | append: '/maxresdefault.jpg'
    assign thumb_fallback = 'https://img.youtube.com/vi/' | append: video_id | append: '/hqdefault.jpg'
  endif
-%}

maxresdefault.jpg gives you a crisp 1280×720 image — but it doesn't exist for every video. Older uploads and low-resolution sources only have hqdefault.jpg. We store the fallback in a data attribute and handle the 404 in JavaScript, which we'll get to shortly.

Building the Facade Markup

The facade is a <button> containing an <img> and an SVG play icon. Using a real <button> rather than a <div onclick> gets you keyboard activation, focus management, and screen reader semantics for free.

<div
  class="ur-yt"
  style="
    --ur-yt-max-width: {{ block.settings.max_width }}px;
    --ur-yt-radius: {{ block.settings.corner_radius }}px;
    --ur-yt-play: {{ block.settings.play_button_color }};
    --ur-yt-ratio: {{ block.settings.aspect_ratio }};
    padding-top: {{ block.settings.padding_top }}px;
    padding-bottom: {{ block.settings.padding_bottom }}px;
  "
  {{ block.shopify_attributes }}
>
  {%- if block.settings.heading != blank -%}
    <h2 class="ur-yt__heading">{{ block.settings.heading | escape }}</h2>
  {%- endif -%}

  <div class="ur-yt__frame">
    <button
      type="button"
      class="ur-yt__facade"
      data-ur-yt-facade
      data-video-id="{{ video_id | escape }}"
      data-start="{{ block.settings.start_seconds }}"
      aria-label="{{ play_label | escape }}"
    >
      <img
        class="ur-yt__thumb"
        src="{{ thumb_src }}"
        data-fallback="{{ thumb_fallback }}"
        alt=""
        width="1280"
        height="720"
        loading="lazy"
        decoding="async"
      >
      <span class="ur-yt__play" aria-hidden="true">
        <svg viewBox="0 0 24 24" width="32" height="32" fill="currentColor" focusable="false">
          <path d="M8 5v14l11-7z"></path>
        </svg>
      </span>
    </button>
  </div>

  {%- if block.settings.caption != blank -%}
    <p class="ur-yt__caption">{{ block.settings.caption | escape }}</p>
  {%- endif -%}
</div>

Several deliberate decisions in there:

{{ block.shopify_attributes }} is required. It renders the data attributes the theme editor uses to highlight and scroll to your block when a merchant selects it in the sidebar. Leave it out and the editing experience breaks in a way that's hard to debug.

CSS custom properties carry the settings. Rather than generating a <style> tag per block — which duplicates rules for every instance on the page — we set variables inline and keep all the actual rules in one cached CSS file. Multiple blocks on the same page each get their own values with zero extra CSS.

alt="" on the thumbnail is correct here. The image is decorative relative to the button, which already carries the accessible name via aria-label. If you also gave the image an alt text, screen readers would announce the video title twice.

width and height are on the image. Combined with the aspect-ratio on the wrapper, this reserves the exact layout box before the image loads. That's your CLS score protected.

The accessible label is built just above the markup:

{%- liquid
  if block.settings.video_title != blank
    assign play_label = 'Play video: ' | append: block.settings.video_title
  else
    assign play_label = 'Play video'
  endif
-%}

If you're shipping to a merchant base outside English, move that string into locales/en.default.json and use {{ 'youtube.play_label' | t }} instead. Theme app extensions support the same translation system as themes.

Styling a Responsive 16:9 Player

The whole layout hinges on one property: aspect-ratio on the frame. Everything inside is absolutely positioned to fill it.

.ur-yt {
  margin: 0 auto;
}

.ur-yt__heading {
  max-width: var(--ur-yt-max-width, 900px);
  margin: 0 auto 0.75rem;
  text-align: center;
}

.ur-yt__frame {
  position: relative;
  width: 100%;
  max-width: var(--ur-yt-max-width, 900px);
  margin: 0 auto;
  aspect-ratio: var(--ur-yt-ratio, 16 / 9);
  border-radius: var(--ur-yt-radius, 8px);
  overflow: hidden;
  background-color: #000;
}

/* Both the facade button and the injected iframe fill the frame exactly. */
.ur-yt__frame > * {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
}

.ur-yt__iframe {
  display: block;
  border: 0;
}

.ur-yt__facade {
  display: block;
  padding: 0;
  border: 0;
  background-color: #000;
  cursor: pointer;
  appearance: none;
}

.ur-yt__thumb {
  display: block;
  width: 100%;
  height: 100%;
  object-fit: cover;
}

The .ur-yt__frame > * rule is doing quiet but important work: the facade button and the iframe that replaces it are styled identically. When JavaScript swaps one for the other, there is no reflow, no flash, no jump. The video appears exactly where the thumbnail was.

Now the play button:

.ur-yt__play {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  display: flex;
  align-items: center;
  justify-content: center;
  width: 68px;
  height: 48px;
  border-radius: 14px;
  background-color: var(--ur-yt-play, #ff0000);
  color: #fff;
  opacity: 0.9;
  transition: opacity 0.2s ease, transform 0.2s ease;
  pointer-events: none;
}

.ur-yt__facade:hover .ur-yt__play,
.ur-yt__facade:focus-visible .ur-yt__play {
  opacity: 1;
  transform: translate(-50%, -50%) scale(1.08);
}

.ur-yt__facade:focus-visible {
  outline: 3px solid currentColor;
  outline-offset: -3px;
}

pointer-events: none on the play button means clicks always land on the button element itself, never on the inner <span> or <svg>. That keeps the JavaScript's closest() lookup simple. (We handle it defensively in JS anyway, but belt and braces.)

Two more rules to be a good citizen:

@media (prefers-reduced-motion: reduce) {
  .ur-yt__play {
    transition: none;
  }
  .ur-yt__facade:hover .ur-yt__play,
  .ur-yt__facade:focus-visible .ur-yt__play {
    transform: translate(-50%, -50%);
  }
}

.ur-yt__caption {
  max-width: var(--ur-yt-max-width, 900px);
  margin: 0.75rem auto 0;
  text-align: center;
  font-size: 0.9rem;
  opacity: 0.8;
}

.ur-yt__placeholder {
  padding: 2rem;
  border: 1px dashed currentColor;
  border-radius: 8px;
  text-align: center;
  opacity: 0.6;
}

Because the aspect ratio is a CSS variable, supporting vertical Shorts is a one-line setting change — 9 / 16 instead of 16 / 9 — with no separate stylesheet or media query.

Swapping in the Real iframe with JavaScript

Here's the part that matters most for correctness in a Shopify context.

Do not bind click handlers to elements on DOMContentLoaded. In the theme editor, Shopify re-renders blocks when a merchant changes a setting, adds a block, or drags one to a new position. Any handler you attached to the old DOM node dies with it, and the block stops responding until the merchant reloads the page. Merchants notice.

The fix is event delegation on document. One listener, attached once, that works for every block on the page — including blocks that didn't exist when the script ran.

(function () {
  'use strict';

  var EMBED_ORIGIN = 'https://www.youtube-nocookie.com';
  var connectionWarmed = false;
  var IFRAME_ALLOW =
    'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share';

  function warmConnection() {
    if (connectionWarmed) return;
    connectionWarmed = true;

    var link = document.createElement('link');
    link.rel = 'preconnect';
    link.href = EMBED_ORIGIN;
    link.crossOrigin = '';
    document.head.appendChild(link);
  }

  function buildIframe(facade) {
    var videoId = facade.getAttribute('data-video-id');
    var start = parseInt(facade.getAttribute('data-start'), 10) || 0;

    var params = ['autoplay=1', 'rel=0', 'modestbranding=1', 'playsinline=1'];
    if (start > 0) {
      params.push('start=' + start);
    }

    var iframe = document.createElement('iframe');
    iframe.className = 'ur-yt__iframe';
    iframe.src = EMBED_ORIGIN + '/embed/' + encodeURIComponent(videoId) + '?' + params.join('&');
    iframe.title = facade.getAttribute('aria-label') || 'YouTube video player';
    iframe.allow = IFRAME_ALLOW;
    iframe.allowFullscreen = true;
    iframe.setAttribute('frameborder', '0');

    return iframe;
  }

  document.addEventListener('click', function (event) {
    var target = event.target;
    if (!(target instanceof Element)) return;

    var facade = target.closest('[data-ur-yt-facade]');
    if (!facade) return;

    var frame = facade.parentNode;
    if (!frame) return;

    var iframe = buildIframe(facade);
    frame.replaceChild(iframe, facade);
    iframe.focus();
  });

  // Warm up DNS + TLS as soon as the user shows intent, so the click feels instant.
  ['pointerover', 'focusin', 'touchstart'].forEach(function (eventName) {
    document.addEventListener(
      eventName,
      function (event) {
        var target = event.target;
        if (target instanceof Element && target.closest('[data-ur-yt-facade]')) {
          warmConnection();
        }
      },
      { passive: true, capture: true },
    );
  });

  // maxresdefault.jpg doesn't exist for every video — fall back to hqdefault.jpg.
  // Note: error events don't bubble, so this listener must use capture.
  document.addEventListener(
    'error',
    function (event) {
      var img = event.target;
      if (!(img instanceof Element) || !img.classList.contains('ur-yt__thumb')) return;

      var fallback = img.getAttribute('data-fallback');
      if (!fallback) return;

      img.removeAttribute('data-fallback'); // prevents an infinite retry loop
      img.src = fallback;
    },
    true,
  );
})();

Three details worth calling out:

autoplay=1 works here — and only here. Browsers block autoplay for unmuted video, unless the play was initiated by a user gesture. Because we create the iframe inside a click handler, the gesture carries over and the video plays with sound. If you ever load the iframe without a click (say, on scroll), you must add mute=1 or nothing will play.

The error listener uses capture. error events fired on an <img> do not bubble up the DOM. Passing true as the third argument catches them during the capture phase instead, which is what makes a single delegated listener possible for every thumbnail on the page.

iframe.focus() after the swap. The user just activated a button that no longer exists. Without moving focus, a keyboard user is dumped back to the top of the document. Focusing the iframe keeps them exactly where they were, and their next Tab press continues from the player.

To load these assets, reference them from the block's schema (covered next) — Shopify handles the CDN URLs and only loads them on pages where the block is present.

Making It Configurable from the Theme Editor

Everything so far is hardcoded to settings that don't exist yet. The {% schema %} tag at the bottom of the block file defines them.

{% schema %}
{
  "name": "YouTube video",
  "target": "section",
  "stylesheet": "youtube-embed.css",
  "javascript": "youtube-embed.js",
  "settings": [
    {
      "type": "header",
      "content": "Video"
    },
    {
      "type": "text",
      "id": "video_url",
      "label": "YouTube URL",
      "info": "Paste any YouTube link — watch, youtu.be, Shorts, or embed."
    },
    {
      "type": "text",
      "id": "video_title",
      "label": "Video title",
      "info": "Used for the accessible label and the player title."
    },
    {
      "type": "number",
      "id": "start_seconds",
      "label": "Start at (seconds)",
      "default": 0
    },
    {
      "type": "image_picker",
      "id": "custom_thumbnail",
      "label": "Custom thumbnail",
      "info": "Optional. Defaults to the YouTube thumbnail."
    },
    {
      "type": "header",
      "content": "Text"
    },
    {
      "type": "text",
      "id": "heading",
      "label": "Heading"
    },
    {
      "type": "text",
      "id": "caption",
      "label": "Caption"
    },
    {
      "type": "header",
      "content": "Layout"
    },
    {
      "type": "select",
      "id": "aspect_ratio",
      "label": "Aspect ratio",
      "options": [
        { "value": "16 / 9", "label": "16:9 (landscape)" },
        { "value": "9 / 16", "label": "9:16 (Shorts)" },
        { "value": "4 / 3", "label": "4:3 (classic)" },
        { "value": "1 / 1", "label": "1:1 (square)" }
      ],
      "default": "16 / 9"
    },
    {
      "type": "range",
      "id": "max_width",
      "label": "Maximum width",
      "min": 320,
      "max": 1400,
      "step": 20,
      "unit": "px",
      "default": 900
    },
    {
      "type": "range",
      "id": "corner_radius",
      "label": "Corner radius",
      "min": 0,
      "max": 40,
      "step": 2,
      "unit": "px",
      "default": 8
    },
    {
      "type": "color",
      "id": "play_button_color",
      "label": "Play button color",
      "default": "#ff0000"
    },
    {
      "type": "range",
      "id": "padding_top",
      "label": "Top padding",
      "min": 0,
      "max": 100,
      "step": 4,
      "unit": "px",
      "default": 24
    },
    {
      "type": "range",
      "id": "padding_bottom",
      "label": "Bottom padding",
      "min": 0,
      "max": 100,
      "step": 4,
      "unit": "px",
      "default": 24
    }
  ]
}
{% endschema %}

A few schema mechanics that trip people up:

"stylesheet" and "javascript" are the right way to load assets. Point them at filenames in your assets/ directory and Shopify injects them for you — deduplicated across multiple instances of the block, and only on pages where the block actually renders. Don't hand-roll <script> tags in the Liquid; you'll load the same file N times for N blocks.

"target": "section" lets merchants add the block inside existing sections (product pages, custom sections, wherever the theme allows app blocks). The alternative, "target": "body", is for blocks that should render once per page outside the normal content flow — sticky bars, popups, cookie notices. A video belongs in the content flow, so "section" it is.

Use liquid as the code fence language, not json. The {% schema %} block is JSON inside a Liquid tag. Editors and linters that treat the whole file as JSON will choke on the surrounding Liquid.

Comments are not allowed in schema JSON. No //, no /* */. A single comment breaks the block silently — it just won't appear in the theme editor's block list, with no error message telling you why.

Complete File

Here's everything, ready to paste.

`extensions/youtube-embed/blocks/youtube-embed.liquid`

{%- liquid
  assign raw_url = block.settings.video_url | strip
  assign video_id = ''

  if raw_url contains 'youtu.be/'
    assign video_id = raw_url | split: 'youtu.be/' | last
  elsif raw_url contains '/embed/'
    assign video_id = raw_url | split: '/embed/' | last
  elsif raw_url contains '/shorts/'
    assign video_id = raw_url | split: '/shorts/' | last
  elsif raw_url contains '/live/'
    assign video_id = raw_url | split: '/live/' | last
  elsif raw_url contains 'v='
    assign video_id = raw_url | split: 'v=' | last
  else
    assign video_id = raw_url
  endif

  assign video_id = video_id | split: '?' | first | split: '&' | first | split: '/' | first | strip

  assign thumb_fallback = ''
  if block.settings.custom_thumbnail != blank
    assign thumb_src = block.settings.custom_thumbnail | image_url: width: 1280
  else
    assign thumb_src = 'https://img.youtube.com/vi/' | append: video_id | append: '/maxresdefault.jpg'
    assign thumb_fallback = 'https://img.youtube.com/vi/' | append: video_id | append: '/hqdefault.jpg'
  endif

  if block.settings.video_title != blank
    assign play_label = 'Play video: ' | append: block.settings.video_title
  else
    assign play_label = 'Play video'
  endif
-%}

{%- if video_id == blank -%}
  {%- if request.design_mode -%}
    <div class="ur-yt__placeholder" {{ block.shopify_attributes }}>
      Add a YouTube URL in the block settings to display a video.
    </div>
  {%- endif -%}
{%- else -%}
  <div
    class="ur-yt"
    style="
      --ur-yt-max-width: {{ block.settings.max_width }}px;
      --ur-yt-radius: {{ block.settings.corner_radius }}px;
      --ur-yt-play: {{ block.settings.play_button_color }};
      --ur-yt-ratio: {{ block.settings.aspect_ratio }};
      padding-top: {{ block.settings.padding_top }}px;
      padding-bottom: {{ block.settings.padding_bottom }}px;
    "
    {{ block.shopify_attributes }}
  >
    {%- if block.settings.heading != blank -%}
      <h2 class="ur-yt__heading">{{ block.settings.heading | escape }}</h2>
    {%- endif -%}

    <div class="ur-yt__frame">
      <button
        type="button"
        class="ur-yt__facade"
        data-ur-yt-facade
        data-video-id="{{ video_id | escape }}"
        data-start="{{ block.settings.start_seconds }}"
        aria-label="{{ play_label | escape }}"
      >
        <img
          class="ur-yt__thumb"
          src="{{ thumb_src }}"
          data-fallback="{{ thumb_fallback }}"
          alt=""
          width="1280"
          height="720"
          loading="lazy"
          decoding="async"
        >
        <span class="ur-yt__play" aria-hidden="true">
          <svg viewBox="0 0 24 24" width="32" height="32" fill="currentColor" focusable="false">
            <path d="M8 5v14l11-7z"></path>
          </svg>
        </span>
      </button>
    </div>

    {%- if block.settings.caption != blank -%}
      <p class="ur-yt__caption">{{ block.settings.caption | escape }}</p>
    {%- endif -%}
  </div>
{%- endif -%}

{% schema %}
{
  "name": "YouTube video",
  "target": "section",
  "stylesheet": "youtube-embed.css",
  "javascript": "youtube-embed.js",
  "settings": [
    {
      "type": "header",
      "content": "Video"
    },
    {
      "type": "text",
      "id": "video_url",
      "label": "YouTube URL",
      "info": "Paste any YouTube link — watch, youtu.be, Shorts, or embed."
    },
    {
      "type": "text",
      "id": "video_title",
      "label": "Video title",
      "info": "Used for the accessible label and the player title."
    },
    {
      "type": "number",
      "id": "start_seconds",
      "label": "Start at (seconds)",
      "default": 0
    },
    {
      "type": "image_picker",
      "id": "custom_thumbnail",
      "label": "Custom thumbnail",
      "info": "Optional. Defaults to the YouTube thumbnail."
    },
    {
      "type": "header",
      "content": "Text"
    },
    {
      "type": "text",
      "id": "heading",
      "label": "Heading"
    },
    {
      "type": "text",
      "id": "caption",
      "label": "Caption"
    },
    {
      "type": "header",
      "content": "Layout"
    },
    {
      "type": "select",
      "id": "aspect_ratio",
      "label": "Aspect ratio",
      "options": [
        { "value": "16 / 9", "label": "16:9 (landscape)" },
        { "value": "9 / 16", "label": "9:16 (Shorts)" },
        { "value": "4 / 3", "label": "4:3 (classic)" },
        { "value": "1 / 1", "label": "1:1 (square)" }
      ],
      "default": "16 / 9"
    },
    {
      "type": "range",
      "id": "max_width",
      "label": "Maximum width",
      "min": 320,
      "max": 1400,
      "step": 20,
      "unit": "px",
      "default": 900
    },
    {
      "type": "range",
      "id": "corner_radius",
      "label": "Corner radius",
      "min": 0,
      "max": 40,
      "step": 2,
      "unit": "px",
      "default": 8
    },
    {
      "type": "color",
      "id": "play_button_color",
      "label": "Play button color",
      "default": "#ff0000"
    },
    {
      "type": "range",
      "id": "padding_top",
      "label": "Top padding",
      "min": 0,
      "max": 100,
      "step": 4,
      "unit": "px",
      "default": 24
    },
    {
      "type": "range",
      "id": "padding_bottom",
      "label": "Bottom padding",
      "min": 0,
      "max": 100,
      "step": 4,
      "unit": "px",
      "default": 24
    }
  ]
}
{% endschema %}

`extensions/youtube-embed/assets/youtube-embed.css`

.ur-yt {
  margin: 0 auto;
}

.ur-yt__heading {
  max-width: var(--ur-yt-max-width, 900px);
  margin: 0 auto 0.75rem;
  text-align: center;
}

.ur-yt__frame {
  position: relative;
  width: 100%;
  max-width: var(--ur-yt-max-width, 900px);
  margin: 0 auto;
  aspect-ratio: var(--ur-yt-ratio, 16 / 9);
  border-radius: var(--ur-yt-radius, 8px);
  overflow: hidden;
  background-color: #000;
}

.ur-yt__frame > * {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
}

.ur-yt__iframe {
  display: block;
  border: 0;
}

.ur-yt__facade {
  display: block;
  padding: 0;
  border: 0;
  background-color: #000;
  cursor: pointer;
  appearance: none;
}

.ur-yt__thumb {
  display: block;
  width: 100%;
  height: 100%;
  object-fit: cover;
}

.ur-yt__play {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  display: flex;
  align-items: center;
  justify-content: center;
  width: 68px;
  height: 48px;
  border-radius: 14px;
  background-color: var(--ur-yt-play, #ff0000);
  color: #fff;
  opacity: 0.9;
  transition: opacity 0.2s ease, transform 0.2s ease;
  pointer-events: none;
}

.ur-yt__facade:hover .ur-yt__play,
.ur-yt__facade:focus-visible .ur-yt__play {
  opacity: 1;
  transform: translate(-50%, -50%) scale(1.08);
}

.ur-yt__facade:focus-visible {
  outline: 3px solid currentColor;
  outline-offset: -3px;
}

.ur-yt__caption {
  max-width: var(--ur-yt-max-width, 900px);
  margin: 0.75rem auto 0;
  text-align: center;
  font-size: 0.9rem;
  opacity: 0.8;
}

.ur-yt__placeholder {
  padding: 2rem;
  border: 1px dashed currentColor;
  border-radius: 8px;
  text-align: center;
  opacity: 0.6;
}

@media (prefers-reduced-motion: reduce) {
  .ur-yt__play {
    transition: none;
  }

  .ur-yt__facade:hover .ur-yt__play,
  .ur-yt__facade:focus-visible .ur-yt__play {
    transform: translate(-50%, -50%);
  }
}

`extensions/youtube-embed/assets/youtube-embed.js`

(function () {
  'use strict';

  var EMBED_ORIGIN = 'https://www.youtube-nocookie.com';
  var IFRAME_ALLOW =
    'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share';
  var connectionWarmed = false;

  function warmConnection() {
    if (connectionWarmed) return;
    connectionWarmed = true;

    var link = document.createElement('link');
    link.rel = 'preconnect';
    link.href = EMBED_ORIGIN;
    link.crossOrigin = '';
    document.head.appendChild(link);
  }

  function buildIframe(facade) {
    var videoId = facade.getAttribute('data-video-id');
    var start = parseInt(facade.getAttribute('data-start'), 10) || 0;

    var params = ['autoplay=1', 'rel=0', 'modestbranding=1', 'playsinline=1'];
    if (start > 0) {
      params.push('start=' + start);
    }

    var iframe = document.createElement('iframe');
    iframe.className = 'ur-yt__iframe';
    iframe.src = EMBED_ORIGIN + '/embed/' + encodeURIComponent(videoId) + '?' + params.join('&');
    iframe.title = facade.getAttribute('aria-label') || 'YouTube video player';
    iframe.allow = IFRAME_ALLOW;
    iframe.allowFullscreen = true;
    iframe.setAttribute('frameborder', '0');

    return iframe;
  }

  document.addEventListener('click', function (event) {
    var target = event.target;
    if (!(target instanceof Element)) return;

    var facade = target.closest('[data-ur-yt-facade]');
    if (!facade) return;

    var frame = facade.parentNode;
    if (!frame) return;

    var iframe = buildIframe(facade);
    frame.replaceChild(iframe, facade);
    iframe.focus();
  });

  ['pointerover', 'focusin', 'touchstart'].forEach(function (eventName) {
    document.addEventListener(
      eventName,
      function (event) {
        var target = event.target;
        if (target instanceof Element && target.closest('[data-ur-yt-facade]')) {
          warmConnection();
        }
      },
      { passive: true, capture: true },
    );
  });

  document.addEventListener(
    'error',
    function (event) {
      var img = event.target;
      if (!(img instanceof Element) || !img.classList.contains('ur-yt__thumb')) return;

      var fallback = img.getAttribute('data-fallback');
      if (!fallback) return;

      img.removeAttribute('data-fallback');
      img.src = fallback;
    },
    true,
  );
})();

Tips and Common Pitfalls

maxresdefault.jpg returns 404 more often than you'd think. Any video uploaded below 720p — and plenty of older ones above it — only has hqdefault.jpg. Without the fallback handler, those blocks render a broken image icon on a black background. Always ship the fallback.

rel=0 no longer removes related videos. It used to. Since a 2018 change, YouTube reinterpreted the parameter: instead of hiding suggestions entirely, it limits them to videos from the same channel. Set the expectation with merchants — there's no supported way to fully suppress end-screen suggestions on a standard embed.

Vertical Shorts need a vertical frame. Embedding a Short at 16:9 gives you a tiny video floating in two black pillars. That's what the aspect ratio setting is for. If you want it automatic, you'd need the YouTube Data API to look up the video's dimensions server-side — a merchant-facing dropdown is far simpler and works offline.

youtube-nocookie.com is not a magic GDPR pass. It defers cookies until playback begins, which is genuinely better — but once someone presses play, YouTube sets its cookies as normal. If your merchants operate under strict consent regimes, the facade needs to sit behind their consent banner. Shopify's Customer Privacy API is the hook for that.

Don't hardcode <script src> in the Liquid. Use the "javascript" and "stylesheet" schema keys. If a merchant adds five video blocks to one page and you injected the tag manually, the browser parses five copies of your script and registers five sets of delegated listeners — meaning every click builds five iframes.

Test inside the theme editor, not just the storefront. The editor is where re-render bugs surface. Add the block, change a setting, drag it to a different position, then click play. If your code binds handlers directly to DOM nodes at load time, this is exactly where it breaks — and it's the first thing a merchant will do.

Set width and height on the thumbnail even though CSS overrides them. The attributes give the browser an intrinsic aspect ratio to reserve space with during layout, before the image bytes arrive. Skipping them is a free CLS penalty.

Watch out for themes that already lazy-load images. Some themes apply their own IntersectionObserver to every <img> and rewrite src/data-src. If your thumbnail disappears, check whether the theme's script has claimed it — namespacing your class (ur-yt__thumb rather than lazyload) usually keeps you out of the way.

Measure before and after. Run Lighthouse on a page with a standard embed, then the same page with the facade. Seeing total blocking time drop is the argument you'll use with the merchant, and it's more persuasive than any explanation of the pattern.

Conclusion

Embedding a YouTube video in Shopify is trivial. Embedding one without paying for it in page speed takes a bit more thought — but not much. The facade pattern is roughly 60 lines of JavaScript, and it turns a multi-hundred-kilobyte third-party dependency into a single lazy-loaded image.

To recap what we built:

A Theme App Extension block merchants can drop into any section
Liquid-only URL parsing that handles watch links, short links, Shorts, live URLs, embed URLs, and bare IDs
A facade that renders a thumbnail and play button with zero third-party JavaScript
Click-to-load with autoplay that works because the browser sees a genuine user gesture
Connection warming on hover, so the click feels instant
Responsive aspect ratios with no layout shift, plus keyboard and screen reader support
Theme editor settings for URL, thumbnail, ratio, width, radius, colors, and spacing

Take the complete files above and adapt them. The pattern generalizes too — Vimeo, Wistia, Google Maps, and Twitter embeds all benefit from exactly the same treatment.

And if you'd rather not maintain this yourself, we ship it as an app.

UR: Smart YouTube Embed

If you're a merchant reading this — or a developer whose client wants video on ten pages by Friday — UR: Smart YouTube Embed does everything above with no code.

Paste any YouTube URL — watch links, short links, Shorts, playlists — and the app handles the rest
Lazy-loaded by default, so videos never drag down your Online Store Speed score
Fully responsive across desktop, tablet, and mobile, with aspect ratio control for vertical Shorts
Customize everything from the theme editor — thumbnail, play button, size, corners, spacing — with a live preview
Add videos anywhere — product pages, collection pages, the homepage, or any custom section
Built as a Theme App Extension, so nothing is left behind in your theme if you uninstall

It's built by UnReact, a Shopify app development studio. We build our apps the way this article describes: performance-first, accessible, and native to the theme editor.

Build it yourself with the code above, or install the app and skip to the part where it's done. Either way, your videos shouldn't cost you your page speed.

References

How to Build a Sticky Add-to-Cart Bar in Shopify with Liquid and JavaScript

Eiji Saito — Mon, 20 Jul 2026 04:09:54 +0000

Introduction
What We'll Build
How Sticky Cart Bars Work
Setting Up the Theme App Extension
Building the Liquid Template
Styling the Sticky Bar
Adding JavaScript for Show/Hide Logic
Handling Variant Selection
Complete File
Tips and Common Pitfalls
Conclusion
UR: Smart Sticky Cart
References

Introduction

Here's a common scenario: a customer lands on your product page, reads the description, scrolls through reviews — and by the time they're ready to buy, the Add to Cart button is nowhere in sight. They have to scroll all the way back up. That friction, however small, costs conversions.

A sticky add-to-cart bar solves this by keeping a compact buy bar pinned to the bottom of the screen whenever the main Add to Cart button scrolls out of the viewport. The customer can add the product to their cart from anywhere on the page without scrolling back up.

In this tutorial, I'll walk you through building a fully functional sticky add-to-cart bar as a Theme App Extension for Shopify. We'll use the Intersection Observer API to detect when the original buy button leaves the viewport, handle variant selection with price and availability updates, and style everything with smooth CSS transitions. By the end, you'll have production-ready code you can drop into any Online Store 2.0 theme.

What We'll Build

The sticky cart bar will:

Appear automatically when the main Add to Cart button scrolls out of view
Hide when the customer scrolls back up to the original button
Display the product image, title, price, and a variant selector
Sync variant selection with the main product form — changing a variant in the sticky bar updates the price, availability, and selected variant
Support smooth slide-up/slide-down animations
Be fully configurable from the theme editor (colors, bar height, z-index)
Work on both desktop and mobile

How Sticky Cart Bars Work

Before we dive into code, let's understand the mechanism. A sticky cart bar involves three moving parts:

1. Visibility Trigger

We need to know when the main Add to Cart button leaves the viewport. There are two common approaches:

Scroll event listener — Listen to scroll events and compare getBoundingClientRect() against the viewport. Simple but fires on every scroll frame, which can cause jank.
Intersection Observer — A browser API purpose-built for detecting when elements enter or leave the viewport. It runs asynchronously off the main thread, so it's far more performant.

We'll use Intersection Observer. It's supported in all modern browsers and is the recommended approach for this pattern.

2. Fixed Positioning

The bar itself uses position: fixed with bottom: 0 to stay pinned to the bottom of the screen. We'll use transform: translateY(100%) to hide it off-screen and translateY(0) to slide it into view.

3. Cart Submission

When the customer clicks "Add to Cart" on the sticky bar, we submit the selected variant to Shopify's /cart/add.js endpoint via the Fetch API. This avoids a full page reload and gives us control over the post-add behavior (e.g., opening a cart drawer or redirecting).

Setting Up the Theme App Extension

Prerequisites

Make sure you have:

A Shopify Partner account
A development store
Shopify CLI installed
An existing Shopify app (or create one with shopify app init)

Generate the Extension

Inside your app directory, run:

shopify app generate extension --template theme_app_extension --name sticky-cart

This creates the following structure:

extensions/
  sticky-cart/
    blocks/
    assets/
    locales/
    snippets/

We'll create two files:

blocks/sticky-cart.liquid — the main Liquid template with the sticky bar markup, JavaScript, and schema
assets/sticky-cart.css — styles for the sticky bar

Let's start building.

Building the Liquid Template

Create the app block file at extensions/sticky-cart/blocks/sticky-cart.liquid.

The Liquid template needs to render the product's image, title, price, variant selector, and an Add to Cart button. It also needs to output data attributes so our JavaScript can access product data without additional API calls.

The Sticky Bar Container

First, let's set up the outer wrapper with product data:

{{ 'sticky-cart.css' | asset_url | stylesheet_tag }}

{% if product.available %}
<div
  id="sticky-cart-bar"
  class="sticky-cart"
  data-product-url="{{ product.url }}"
  style="
    --sticky-cart-bg: {{ block.settings.background_color }};
    --sticky-cart-text: {{ block.settings.text_color }};
    --sticky-cart-btn-bg: {{ block.settings.button_color }};
    --sticky-cart-btn-text: {{ block.settings.button_text_color }};
    --sticky-cart-z-index: {{ block.settings.z_index }};
  "
>
  <div class="sticky-cart__inner">
    <!-- Product info, variant selector, and button will go here -->
  </div>
</div>
{% endif %}

We wrap everything in {% if product.available %} — there's no point showing a buy bar for sold-out products. Merchant settings are passed as CSS custom properties, keeping the Liquid template clean and all visual styling in the CSS file.

Product Information

Inside the .sticky-cart__inner container, we display the product image and title:

<div class="sticky-cart__product">
  {% if product.featured_image %}
    <img
      class="sticky-cart__image"
      src="{{ product.featured_image | image_url: width: 80 }}"
      alt="{{ product.featured_image.alt | escape }}"
      width="40"
      height="40"
      loading="lazy"
    />
  {% endif %}
  <div class="sticky-cart__details">
    <a href="{{ product.url }}" class="sticky-cart__title">
      {{ product.title }}
    </a>
    <div class="sticky-cart__price" id="sticky-cart-price">
      {{ product.selected_or_first_available_variant.price | money }}
    </div>
  </div>
</div>

We use image_url: width: 80 to request a small image — the bar only needs a thumbnail, and requesting a full-size image would waste bandwidth. The id="sticky-cart-price" lets our JavaScript update the price when the customer changes the variant.

Variant Selector

If the product has more than one variant, we render a <select> dropdown. For single-variant products, we output a hidden input instead:

<div class="sticky-cart__actions">
  {% if product.variants.size > 1 %}
    <div class="sticky-cart__variant-wrapper">
      <select
        id="sticky-cart-variant-select"
        class="sticky-cart__variant-select"
        aria-label="Select variant"
      >
        {% for variant in product.variants %}
          <option
            value="{{ variant.id }}"
            data-price="{{ variant.price | money }}"
            data-available="{{ variant.available }}"
            {% if variant == product.selected_or_first_available_variant %}
              selected
            {% endif %}
          >
            {{ variant.title }}
          </option>
        {% endfor %}
      </select>
    </div>
  {% else %}
    <input
      type="hidden"
      id="sticky-cart-variant-select"
      value="{{ product.selected_or_first_available_variant.id }}"
    />
  {% endif %}

  <button
    type="button"
    id="sticky-cart-add-btn"
    class="sticky-cart__add-btn"
    {% unless product.selected_or_first_available_variant.available %}
      disabled
    {% endunless %}
  >
    {{ block.settings.button_text }}
  </button>
</div>

Each <option> carries data-price and data-available attributes. This way, when the customer selects a different variant, JavaScript can instantly update the price and disable the button for out-of-stock variants — no additional API calls needed.

Styling the Sticky Bar

Create the stylesheet at extensions/sticky-cart/assets/sticky-cart.css.

The key CSS technique here is using transform: translateY(100%) to keep the bar hidden below the viewport, and transitioning to translateY(0) when it should be visible. This is smoother than toggling display: none because the browser can hardware-accelerate transform animations.

.sticky-cart {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  z-index: var(--sticky-cart-z-index, 999);
  background-color: var(--sticky-cart-bg, #ffffff);
  color: var(--sticky-cart-text, #333333);
  box-shadow: 0 -2px 10px rgba(0, 0, 0, 0.1);
  transform: translateY(100%);
  transition: transform 0.3s ease;
  will-change: transform;
}

.sticky-cart.is-visible {
  transform: translateY(0);
}

.sticky-cart__inner {
  display: flex;
  align-items: center;
  justify-content: space-between;
  max-width: 1200px;
  margin: 0 auto;
  padding: 10px 20px;
  gap: 16px;
}

.sticky-cart__product {
  display: flex;
  align-items: center;
  gap: 12px;
  flex: 1;
  min-width: 0;
}

.sticky-cart__image {
  width: 40px;
  height: 40px;
  object-fit: cover;
  border-radius: 4px;
  flex-shrink: 0;
}

.sticky-cart__details {
  min-width: 0;
}

.sticky-cart__title {
  display: block;
  font-size: 14px;
  font-weight: 600;
  color: var(--sticky-cart-text, #333333);
  text-decoration: none;
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}

.sticky-cart__title:hover {
  text-decoration: underline;
}

.sticky-cart__price {
  font-size: 14px;
  font-weight: 700;
  margin-top: 2px;
}

.sticky-cart__actions {
  display: flex;
  align-items: center;
  gap: 10px;
  flex-shrink: 0;
}

.sticky-cart__variant-select {
  padding: 8px 12px;
  border: 1px solid #ddd;
  border-radius: 4px;
  font-size: 13px;
  background-color: #fff;
  cursor: pointer;
  max-width: 160px;
}

.sticky-cart__add-btn {
  padding: 10px 24px;
  border: none;
  border-radius: 4px;
  font-size: 14px;
  font-weight: 600;
  cursor: pointer;
  background-color: var(--sticky-cart-btn-bg, #333333);
  color: var(--sticky-cart-btn-text, #ffffff);
  transition: opacity 0.2s ease;
  white-space: nowrap;
}

.sticky-cart__add-btn:hover {
  opacity: 0.85;
}

.sticky-cart__add-btn:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

/* Mobile styles */
@media (max-width: 768px) {
  .sticky-cart__inner {
    flex-wrap: wrap;
    padding: 8px 12px;
    gap: 8px;
  }

  .sticky-cart__product {
    flex: 1 1 100%;
  }

  .sticky-cart__actions {
    flex: 1 1 100%;
    justify-content: stretch;
  }

  .sticky-cart__variant-select {
    flex: 1;
  }

  .sticky-cart__add-btn {
    flex: 1;
  }
}

A few things worth noting about these styles:

will-change: transform — Hints to the browser that this element's transform will change, so it can prepare by promoting the element to its own compositing layer. This ensures silky-smooth animation.
min-width: 0 on .sticky-cart__product — Without this, flexbox children won't shrink below their content size, and long product titles would blow out the layout. min-width: 0 lets the title truncate with text-overflow: ellipsis.
Mobile layout — On screens smaller than 768px, the bar wraps into two rows: product info on top, variant selector and button stretching full-width on the bottom. This gives the button a tap-friendly size on mobile.

Adding JavaScript for Show/Hide Logic

Now for the core behavior. We need to:

Find the main product form's Add to Cart button on the page
Observe it with an Intersection Observer
Show the sticky bar when the button leaves the viewport, hide it when it comes back

Add this <script> tag at the bottom of your sticky-cart.liquid file (before the {% schema %} block):

<script>
  (function () {
    const stickyBar = document.getElementById('sticky-cart-bar');
    if (!stickyBar) return;

    function findMainAddToCartButton() {
      const mainForm = document.querySelector(
        'form[action="/cart/add"]:not(.sticky-cart form)'
      );
      if (!mainForm) return null;

      return (
        mainForm.querySelector('[name="add"]') ||
        mainForm.querySelector('button[type="submit"]')
      );
    }

    function initObserver() {
      const targetButton = findMainAddToCartButton();
      if (!targetButton) return;

      const observer = new IntersectionObserver(
        (entries) => {
          entries.forEach((entry) => {
            if (entry.isIntersecting) {
              stickyBar.classList.remove('is-visible');
            } else {
              stickyBar.classList.add('is-visible');
            }
          });
        },
        { threshold: 0 }
      );

      observer.observe(targetButton);
    }

    if (document.readyState === 'loading') {
      document.addEventListener('DOMContentLoaded', initObserver);
    } else {
      initObserver();
    }
  })();
</script>

Let's break this down:

findMainAddToCartButton() — We look for the product page's original form[action="/cart/add"] and grab its submit button. The :not(.sticky-cart form) exclusion ensures we don't accidentally observe our own sticky bar's button. Most Shopify themes use [name="add"] for their Add to Cart button, but we fall back to button[type="submit"] for broader compatibility.

IntersectionObserver — The callback fires whenever the observed button enters or leaves the viewport. entry.isIntersecting is true when the button is visible, false when it's scrolled away. We toggle the is-visible class accordingly, which triggers the CSS transform transition.

threshold: 0 — The callback fires as soon as even a single pixel of the target enters or leaves the viewport. This gives the snappiest response. You could set this to 1 if you only want the sticky bar to appear when the button is completely out of view.

Handling Variant Selection

When the customer selects a different variant in the sticky bar, we need to update three things:

The displayed price
The button's disabled state (for sold-out variants)
The main product form on the page (so both forms stay in sync)

Add this script block alongside the observer code:

<script>
  (function () {
    const variantSelect = document.getElementById('sticky-cart-variant-select');
    const priceEl = document.getElementById('sticky-cart-price');
    const addBtn = document.getElementById('sticky-cart-add-btn');

    if (!variantSelect || !addBtn) return;

    // Update price and availability when variant changes
    if (variantSelect.tagName === 'SELECT') {
      variantSelect.addEventListener('change', function () {
        const selected = this.options[this.selectedIndex];
        const price = selected.dataset.price;
        const available = selected.dataset.available === 'true';

        if (priceEl && price) {
          priceEl.textContent = price;
        }

        addBtn.disabled = !available;
        addBtn.textContent = available
          ? '{{ block.settings.button_text }}'
          : '{{ block.settings.sold_out_text }}';

        // Sync with main product form
        syncMainForm(this.value);
      });
    }

    function syncMainForm(variantId) {
      // Update the URL so the page reflects the selected variant
      const url = new URL(window.location);
      url.searchParams.set('variant', variantId);
      window.history.replaceState({}, '', url);

      // Dispatch a change event on the main form's variant input
      const mainForm = document.querySelector(
        'form[action="/cart/add"]:not(.sticky-cart form)'
      );
      if (!mainForm) return;

      const mainVariantInput = mainForm.querySelector(
        'select[name="id"], input[name="id"]'
      );
      if (mainVariantInput) {
        mainVariantInput.value = variantId;
        mainVariantInput.dispatchEvent(new Event('change', { bubbles: true }));
      }
    }

    // Add to Cart handler
    addBtn.addEventListener('click', function () {
      const variantId =
        variantSelect.tagName === 'SELECT'
          ? variantSelect.value
          : variantSelect.value;

      if (!variantId) return;

      addBtn.disabled = true;
      addBtn.textContent = '{{ block.settings.adding_text }}';

      fetch('/cart/add.js', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          items: [{ id: parseInt(variantId), quantity: 1 }],
        }),
      })
        .then((response) => {
          if (!response.ok) throw new Error('Add to cart failed');
          return response.json();
        })
        .then(() => {
          addBtn.textContent = '{{ block.settings.added_text }}';
          setTimeout(() => {
            addBtn.disabled = false;
            addBtn.textContent = '{{ block.settings.button_text }}';
          }, 2000);

          // Trigger cart update event for themes that listen for it
          document.dispatchEvent(
            new CustomEvent('cart:updated', { bubbles: true })
          );
        })
        .catch((error) => {
          console.error('Sticky cart error:', error);
          addBtn.disabled = false;
          addBtn.textContent = '{{ block.settings.button_text }}';
        });
    });
  })();
</script>

Let's look at the key decisions:

syncMainForm() — When the customer picks a variant in the sticky bar, we update the URL's variant query parameter with history.replaceState. This ensures the page URL reflects the selected variant (which matters for shared links and analytics). We also find the main form's variant <select> or <input> and change its value, dispatching a change event so the theme's own JavaScript picks up the change and updates things like the product image gallery.

/cart/add.js — Shopify's Ajax Cart API. We POST a JSON body with the variant ID and quantity. This is the standard way to add items without a full page reload. The response contains the added line item, but we don't need it here — we just show a success state.

cart:updated CustomEvent — Many Shopify themes (including Dawn) listen for custom events to update the cart drawer or cart icon count. By dispatching this event, the sticky bar integrates smoothly with the theme's existing cart behavior. Some themes use different event names (cart:refresh, ajaxCart:updated), but cart:updated is the most common convention.

Button state feedback — We cycle the button through three states: the default text → "Adding..." → "Added!" → back to default. This gives the customer clear feedback that their action was registered without needing a modal or notification. The 2-second delay before resetting lets the customer see the confirmation.

Complete File

Here's the complete sticky-cart.liquid file — everything in one place so you can copy it directly into your project:

extensions/sticky-cart/blocks/sticky-cart.liquid

{{ 'sticky-cart.css' | asset_url | stylesheet_tag }}

{% if product.available %}
<div
  id="sticky-cart-bar"
  class="sticky-cart"
  data-product-url="{{ product.url }}"
  style="
    --sticky-cart-bg: {{ block.settings.background_color }};
    --sticky-cart-text: {{ block.settings.text_color }};
    --sticky-cart-btn-bg: {{ block.settings.button_color }};
    --sticky-cart-btn-text: {{ block.settings.button_text_color }};
    --sticky-cart-z-index: {{ block.settings.z_index }};
  "
>
  <div class="sticky-cart__inner">
    <div class="sticky-cart__product">
      {% if product.featured_image %}
        <img
          class="sticky-cart__image"
          src="{{ product.featured_image | image_url: width: 80 }}"
          alt="{{ product.featured_image.alt | escape }}"
          width="40"
          height="40"
          loading="lazy"
        />
      {% endif %}
      <div class="sticky-cart__details">
        <a href="{{ product.url }}" class="sticky-cart__title">
          {{ product.title }}
        </a>
        <div class="sticky-cart__price" id="sticky-cart-price">
          {{ product.selected_or_first_available_variant.price | money }}
        </div>
      </div>
    </div>

    <div class="sticky-cart__actions">
      {% if product.variants.size > 1 %}
        <div class="sticky-cart__variant-wrapper">
          <select
            id="sticky-cart-variant-select"
            class="sticky-cart__variant-select"
            aria-label="Select variant"
          >
            {% for variant in product.variants %}
              <option
                value="{{ variant.id }}"
                data-price="{{ variant.price | money }}"
                data-available="{{ variant.available }}"
                {% if variant == product.selected_or_first_available_variant %}
                  selected
                {% endif %}
              >
                {{ variant.title }}
              </option>
            {% endfor %}
          </select>
        </div>
      {% else %}
        <input
          type="hidden"
          id="sticky-cart-variant-select"
          value="{{ product.selected_or_first_available_variant.id }}"
        />
      {% endif %}

      <button
        type="button"
        id="sticky-cart-add-btn"
        class="sticky-cart__add-btn"
        {% unless product.selected_or_first_available_variant.available %}
          disabled
        {% endunless %}
      >
        {{ block.settings.button_text }}
      </button>
    </div>
  </div>
</div>

<script>
  (function () {
    const stickyBar = document.getElementById('sticky-cart-bar');
    if (!stickyBar) return;

    // --- Intersection Observer: show/hide sticky bar ---
    function findMainAddToCartButton() {
      const mainForm = document.querySelector(
        'form[action="/cart/add"]:not(.sticky-cart form)'
      );
      if (!mainForm) return null;

      return (
        mainForm.querySelector('[name="add"]') ||
        mainForm.querySelector('button[type="submit"]')
      );
    }

    function initObserver() {
      const targetButton = findMainAddToCartButton();
      if (!targetButton) return;

      const observer = new IntersectionObserver(
        (entries) => {
          entries.forEach((entry) => {
            if (entry.isIntersecting) {
              stickyBar.classList.remove('is-visible');
            } else {
              stickyBar.classList.add('is-visible');
            }
          });
        },
        { threshold: 0 }
      );

      observer.observe(targetButton);
    }

    if (document.readyState === 'loading') {
      document.addEventListener('DOMContentLoaded', initObserver);
    } else {
      initObserver();
    }

    // --- Variant selection and Add to Cart ---
    const variantSelect = document.getElementById('sticky-cart-variant-select');
    const priceEl = document.getElementById('sticky-cart-price');
    const addBtn = document.getElementById('sticky-cart-add-btn');

    if (!variantSelect || !addBtn) return;

    if (variantSelect.tagName === 'SELECT') {
      variantSelect.addEventListener('change', function () {
        const selected = this.options[this.selectedIndex];
        const price = selected.dataset.price;
        const available = selected.dataset.available === 'true';

        if (priceEl && price) {
          priceEl.textContent = price;
        }

        addBtn.disabled = !available;
        addBtn.textContent = available
          ? '{{ block.settings.button_text }}'
          : '{{ block.settings.sold_out_text }}';

        syncMainForm(this.value);
      });
    }

    function syncMainForm(variantId) {
      const url = new URL(window.location);
      url.searchParams.set('variant', variantId);
      window.history.replaceState({}, '', url);

      const mainForm = document.querySelector(
        'form[action="/cart/add"]:not(.sticky-cart form)'
      );
      if (!mainForm) return;

      const mainVariantInput = mainForm.querySelector(
        'select[name="id"], input[name="id"]'
      );
      if (mainVariantInput) {
        mainVariantInput.value = variantId;
        mainVariantInput.dispatchEvent(new Event('change', { bubbles: true }));
      }
    }

    addBtn.addEventListener('click', function () {
      const variantId = variantSelect.value;
      if (!variantId) return;

      addBtn.disabled = true;
      addBtn.textContent = '{{ block.settings.adding_text }}';

      fetch('/cart/add.js', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          items: [{ id: parseInt(variantId), quantity: 1 }],
        }),
      })
        .then((response) => {
          if (!response.ok) throw new Error('Add to cart failed');
          return response.json();
        })
        .then(() => {
          addBtn.textContent = '{{ block.settings.added_text }}';
          setTimeout(() => {
            addBtn.disabled = false;
            addBtn.textContent = '{{ block.settings.button_text }}';
          }, 2000);

          document.dispatchEvent(
            new CustomEvent('cart:updated', { bubbles: true })
          );
        })
        .catch((error) => {
          console.error('Sticky cart error:', error);
          addBtn.disabled = false;
          addBtn.textContent = '{{ block.settings.button_text }}';
        });
    });
  })();
</script>
{% endif %}

{% schema %}
{
  "name": "Sticky Cart Bar",
  "target": "section",
  "settings": [
    {
      "type": "color",
      "id": "background_color",
      "label": "Background color",
      "default": "#ffffff"
    },
    {
      "type": "color",
      "id": "text_color",
      "label": "Text color",
      "default": "#333333"
    },
    {
      "type": "color",
      "id": "button_color",
      "label": "Button color",
      "default": "#333333"
    },
    {
      "type": "color",
      "id": "button_text_color",
      "label": "Button text color",
      "default": "#ffffff"
    },
    {
      "type": "text",
      "id": "button_text",
      "label": "Button text",
      "default": "Add to Cart"
    },
    {
      "type": "text",
      "id": "adding_text",
      "label": "Adding text",
      "default": "Adding..."
    },
    {
      "type": "text",
      "id": "added_text",
      "label": "Added text",
      "default": "Added!"
    },
    {
      "type": "text",
      "id": "sold_out_text",
      "label": "Sold out text",
      "default": "Sold Out"
    },
    {
      "type": "range",
      "id": "z_index",
      "label": "Z-index",
      "min": 1,
      "max": 9999,
      "step": 1,
      "default": 999,
      "info": "Adjust if the bar appears behind other elements"
    }
  ],
  "templates": ["product"]
}
{% endschema %}

extensions/sticky-cart/assets/sticky-cart.css

.sticky-cart {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  z-index: var(--sticky-cart-z-index, 999);
  background-color: var(--sticky-cart-bg, #ffffff);
  color: var(--sticky-cart-text, #333333);
  box-shadow: 0 -2px 10px rgba(0, 0, 0, 0.1);
  transform: translateY(100%);
  transition: transform 0.3s ease;
  will-change: transform;
}

.sticky-cart.is-visible {
  transform: translateY(0);
}

.sticky-cart__inner {
  display: flex;
  align-items: center;
  justify-content: space-between;
  max-width: 1200px;
  margin: 0 auto;
  padding: 10px 20px;
  gap: 16px;
}

.sticky-cart__product {
  display: flex;
  align-items: center;
  gap: 12px;
  flex: 1;
  min-width: 0;
}

.sticky-cart__image {
  width: 40px;
  height: 40px;
  object-fit: cover;
  border-radius: 4px;
  flex-shrink: 0;
}

.sticky-cart__details {
  min-width: 0;
}

.sticky-cart__title {
  display: block;
  font-size: 14px;
  font-weight: 600;
  color: var(--sticky-cart-text, #333333);
  text-decoration: none;
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}

.sticky-cart__title:hover {
  text-decoration: underline;
}

.sticky-cart__price {
  font-size: 14px;
  font-weight: 700;
  margin-top: 2px;
}

.sticky-cart__actions {
  display: flex;
  align-items: center;
  gap: 10px;
  flex-shrink: 0;
}

.sticky-cart__variant-select {
  padding: 8px 12px;
  border: 1px solid #ddd;
  border-radius: 4px;
  font-size: 13px;
  background-color: #fff;
  cursor: pointer;
  max-width: 160px;
}

.sticky-cart__add-btn {
  padding: 10px 24px;
  border: none;
  border-radius: 4px;
  font-size: 14px;
  font-weight: 600;
  cursor: pointer;
  background-color: var(--sticky-cart-btn-bg, #333333);
  color: var(--sticky-cart-btn-text, #ffffff);
  transition: opacity 0.2s ease;
  white-space: nowrap;
}

.sticky-cart__add-btn:hover {
  opacity: 0.85;
}

.sticky-cart__add-btn:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

@media (max-width: 768px) {
  .sticky-cart__inner {
    flex-wrap: wrap;
    padding: 8px 12px;
    gap: 8px;
  }

  .sticky-cart__product {
    flex: 1 1 100%;
  }

  .sticky-cart__actions {
    flex: 1 1 100%;
    justify-content: stretch;
  }

  .sticky-cart__variant-select {
    flex: 1;
  }

  .sticky-cart__add-btn {
    flex: 1;
  }
}

Tips and Common Pitfalls

Z-index Conflicts

Many Shopify themes use high z-index values for headers, modals, and overlays. If the sticky bar appears behind other elements, increase the z-index in the theme editor settings. The default of 999 works for most themes, but some may need 9999 or higher. That's why we made it configurable.

Mobile Bottom Navigation

Some themes add their own fixed-position bottom navigation or chat widgets on mobile. If both exist, they'll overlap. Test on mobile and consider adding a bottom offset via a setting if needed. A common pattern is to detect other fixed elements and adjust accordingly, but for a Theme App Extension, keeping it simple with a configurable z-index is the pragmatic choice.

Cart Drawer Integration

The cart:updated custom event works with many themes out of the box, but not all. If the theme's cart drawer doesn't open or the cart count doesn't update after adding via the sticky bar, check what event the theme listens for. In Shopify's Dawn theme, you may need to dispatch a cart:refresh event or trigger a section rendering update via the Section Rendering API.

Accessibility

The sticky bar uses aria-label on the variant selector and provides visual feedback through button state changes. For even better accessibility, consider adding an aria-live="polite" region that announces when an item has been added to the cart — screen reader users won't see the button text change.

Performance

The Intersection Observer API is lightweight and runs off the main thread, so it won't cause scroll jank. However, be mindful of the CSS box-shadow on the sticky bar — on low-end mobile devices, large box-shadows on fixed-position elements can sometimes cause repaint issues. If you notice performance problems, consider using a simpler border instead of a shadow.

Conclusion

We've built a fully functional sticky add-to-cart bar that enhances the shopping experience by keeping the buy action always within reach. The implementation uses modern browser APIs — Intersection Observer for performant visibility detection, the Fetch API for seamless cart additions, and CSS transforms for smooth animations.

The bar handles variant selection with instant price and availability updates, syncs with the main product form, and integrates with theme cart drawers through custom events. All visual properties are configurable from the theme editor, making it flexible enough for any store's branding.

If you'd rather skip the implementation and get a polished sticky cart with more advanced features out of the box, check out UR: Smart Sticky Cart below.

UR: Smart Sticky Cart

If you want a sticky cart solution without writing any code, UR: Smart Sticky Cart by UnReact provides a ready-to-use sticky add-to-cart bar with advanced features:

Zero-code setup — Install and configure entirely from the Shopify theme editor
Multiple display styles — Choose from a compact bar, a full-width bar, or a floating button
Smart visibility logic — Automatically shows/hides based on the page's Add to Cart button position
Full variant support — Variant selector with real-time price and availability updates
Mobile-optimized design — Responsive layout that adapts to any screen size
Customizable appearance — Colors, fonts, button styles, and animations are all configurable

UR: Smart Sticky Cart on the Shopify App Store

References

How to Add Breadcrumb Navigation to Shopify Using Theme App Extensions — A Complete Guide

Eiji Saito — Mon, 06 Jul 2026 08:26:32 +0000

Introduction
What We'll Build
What is a Theme App Extension?
Creating the Extension
Building the Breadcrumb Markup
Styling the Breadcrumbs
Adding JSON-LD Structured Data
Making It Configurable from the Theme Editor
Complete File
Things to Watch Out For
Conclusion
UR: Smart Breadcrumbs
References

Introduction

Breadcrumb navigation is one of those small UI elements that punches well above its weight. For users, breadcrumbs provide a clear sense of location within a store and a quick way to jump back to parent categories. For search engines, breadcrumbs provide structured hierarchy signals that improve how your pages appear in search results — Google can display breadcrumb trails directly in SERPs when it detects proper markup.

Despite this, many Shopify themes either lack breadcrumbs entirely or offer limited, hard-coded implementations that merchants can't customize. Building breadcrumbs as a Theme App Extension solves this perfectly: merchants get a configurable breadcrumb block they can place anywhere in the theme editor, and your code stays completely isolated from the theme's source files.

In this tutorial, I'll walk you through building a fully customizable breadcrumb navigation app block for Shopify. We'll handle every major page type — products, collections, articles, blogs, and static pages — and output JSON-LD structured data so search engines can parse the breadcrumb trail. By the end, you'll have production-ready code that merchants can configure from the theme editor with zero coding.

What We'll Build

Here's the finished breadcrumb navigation on a product page:

Merchants configure the delimiter, colors, font size, and mobile visibility directly from the theme editor:

The breadcrumb block will:

Automatically generate the correct breadcrumb trail for products, collections, articles, blogs, and pages
Output JSON-LD structured data for SEO
Let merchants customize the delimiter, font size, text color, link color, and home link text
Support toggling visibility on mobile and desktop independently
Work across all Online Store 2.0 themes

What is a Theme App Extension?

Theme App Extensions let Shopify app developers inject UI components — called app blocks — into a merchant's theme without touching the theme's source code.

Why this matters for breadcrumbs:

No theme code editing — Merchants add the breadcrumb block via the theme editor, just like any native section or block.
Theme-safe — Your code lives inside your app. Theme updates won't overwrite or break your breadcrumbs.
Uninstall-clean — When the app is uninstalled, the breadcrumb block is automatically removed. No leftover Liquid snippets.

App blocks are built with Liquid, CSS, and JavaScript — the same stack used in Shopify themes. If you've customized a Shopify theme before, you already know the tools.

For more details, see the official Shopify documentation on Theme App Extensions.

Creating the Extension

Prerequisites

Make sure you have:

A Shopify Partner account
A development store
Shopify CLI installed
An existing Shopify app (or create one with shopify app init)

Generate the Extension

Inside your app directory, run:

shopify app generate extension --template theme_app_extension --name smart-breadcrumbs

This creates the following structure:

extensions/
  smart-breadcrumbs/
    blocks/
    assets/
    locales/
    snippets/

Directory Overview

Directory	Purpose
`blocks/`	Liquid files that become app blocks in the theme editor
`assets/`	CSS and JavaScript files
`locales/`	Translation files for multi-language support
`snippets/`	Reusable Liquid snippets

We'll create three files:

blocks/breadcrumbs.liquid — the main Liquid template with breadcrumb logic and schema
assets/breadcrumbs.css — styles for the breadcrumb component

Let's start building.

Building the Breadcrumb Markup

Create the app block file at extensions/smart-breadcrumbs/blocks/breadcrumbs.liquid.

The core challenge with breadcrumbs on Shopify is that different page types require different breadcrumb structures. A product page might show Home > Collection > Product, while a blog article shows Home > Blog > Article. We need to detect the current page type using the template object and build the trail accordingly.

The Breadcrumb Container

First, let's set up the outer wrapper and the Home link, which is common to every page type:

{{ 'breadcrumbs.css' | asset_url | stylesheet_tag }}

{% assign delimiter = block.settings.delimiter %}
{% assign home_text = block.settings.home_text %}

<nav
  class="app-breadcrumbs"
  aria-label="Breadcrumb"
  style="
    --breadcrumb-font-size: {{ block.settings.font_size }}px;
    --breadcrumb-text-color: {{ block.settings.text_color }};
    --breadcrumb-link-color: {{ block.settings.link_color }};
    --breadcrumb-delimiter-color: {{ block.settings.delimiter_color }};
    {% if block.settings.show_on_mobile == false %}
      --breadcrumb-mobile-display: none;
    {% endif %}
    {% if block.settings.show_on_desktop == false %}
      --breadcrumb-desktop-display: none;
    {% endif %}
  "
>
  <ol class="app-breadcrumbs__list">
    <li class="app-breadcrumbs__item">
      <a href="/" class="app-breadcrumbs__link">{{ home_text }}</a>
    </li>

    <!-- Page-type-specific crumbs will go here -->

  </ol>
</nav>

We pass merchant settings as CSS custom properties through inline styles. This keeps the Liquid template clean and gives us a single place to consume settings in CSS. The aria-label="Breadcrumb" attribute tells screen readers this is a breadcrumb navigation landmark.

Handling Each Page Type

Now let's fill in the breadcrumb trail for each page type. We'll use Shopify's template.name and template.suffix to detect where we are.

Product Pages

Product pages are the most common breadcrumb use case. When a customer arrives at a product from a collection, Shopify makes the referring collection available through collection. If no collection context exists (e.g., the customer arrived via a direct link), we fall back to the product's first collection:

{% if template.name == 'product' %}
  {% if collection %}
    {% assign current_collection = collection %}
  {% elsif product.collections.size > 0 %}
    {% assign current_collection = product.collections[0] %}
  {% endif %}

  {% if current_collection %}
    <li class="app-breadcrumbs__item">
      <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
      <a href="{{ current_collection.url }}" class="app-breadcrumbs__link">
        {{ current_collection.title }}
      </a>
    </li>
  {% endif %}

  <li class="app-breadcrumbs__item app-breadcrumbs__item--current" aria-current="page">
    <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
    <span class="app-breadcrumbs__current">{{ product.title }}</span>
  </li>
{% endif %}

A few things to note:

The collection object is automatically populated by Shopify when a customer navigates from a collection page to a product. This is why breadcrumbs on product pages can show the correct parent collection contextually.
We use aria-current="page" on the last crumb to indicate the current page to assistive technologies.
The current page (last crumb) is rendered as a <span>, not a link — linking to the current page is bad UX and bad for accessibility.

Collection Pages

Collection pages are straightforward — just Home > Collection Name:

{% if template.name == 'collection' %}
  <li class="app-breadcrumbs__item app-breadcrumbs__item--current" aria-current="page">
    <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
    <span class="app-breadcrumbs__current">{{ collection.title }}</span>
  </li>
{% endif %}

Blog Article Pages

Articles live under a blog, so the trail is Home > Blog > Article:

{% if template.name == 'article' %}
  <li class="app-breadcrumbs__item">
    <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
    <a href="{{ blog.url }}" class="app-breadcrumbs__link">
      {{ blog.title }}
    </a>
  </li>
  <li class="app-breadcrumbs__item app-breadcrumbs__item--current" aria-current="page">
    <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
    <span class="app-breadcrumbs__current">{{ article.title }}</span>
  </li>
{% endif %}

Blog Pages

When viewing the blog index (list of articles), the trail is just Home > Blog:

{% if template.name == 'blog' %}
  <li class="app-breadcrumbs__item app-breadcrumbs__item--current" aria-current="page">
    <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
    <span class="app-breadcrumbs__current">{{ blog.title }}</span>
  </li>
{% endif %}

Static Pages

Static pages (About Us, Contact, etc.) follow the same simple pattern:

{% if template.name == 'page' %}
  <li class="app-breadcrumbs__item app-breadcrumbs__item--current" aria-current="page">
    <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
    <span class="app-breadcrumbs__current">{{ page.title }}</span>
  </li>
{% endif %}

Search and Cart Pages

Search results and cart pages deserve breadcrumbs too:

{% if template.name == 'search' %}
  <li class="app-breadcrumbs__item app-breadcrumbs__item--current" aria-current="page">
    <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
    <span class="app-breadcrumbs__current">Search</span>
  </li>
{% endif %}

{% if template.name == 'cart' %}
  <li class="app-breadcrumbs__item app-breadcrumbs__item--current" aria-current="page">
    <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
    <span class="app-breadcrumbs__current">Cart</span>
  </li>
{% endif %}

Styling the Breadcrumbs

Create extensions/smart-breadcrumbs/assets/breadcrumbs.css:

.app-breadcrumbs {
  padding: 12px 0;
  font-size: var(--breadcrumb-font-size, 14px);
  color: var(--breadcrumb-text-color, #666);
  line-height: 1.5;
}

.app-breadcrumbs__list {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  list-style: none;
  margin: 0;
  padding: 0;
  gap: 4px;
}

.app-breadcrumbs__item {
  display: flex;
  align-items: center;
  gap: 4px;
}

.app-breadcrumbs__link {
  color: var(--breadcrumb-link-color, #333);
  text-decoration: none;
  transition: opacity 0.2s ease;
}

.app-breadcrumbs__link:hover {
  opacity: 0.7;
  text-decoration: underline;
}

.app-breadcrumbs__delimiter {
  color: var(--breadcrumb-delimiter-color, #999);
  user-select: none;
}

.app-breadcrumbs__current {
  color: var(--breadcrumb-text-color, #666);
}

/* Responsive visibility */
@media screen and (max-width: 749px) {
  .app-breadcrumbs {
    display: var(--breadcrumb-mobile-display, block);
  }
}

@media screen and (min-width: 750px) {
  .app-breadcrumbs {
    display: var(--breadcrumb-desktop-display, block);
  }
}

Key styling decisions:

Flexbox with flex-wrap — breadcrumbs wrap gracefully on narrow screens instead of overflowing.
CSS custom properties — all colors and sizes come from the Liquid template's inline styles, which read from merchant settings. This means zero JavaScript is needed for customization.
Responsive visibility — the --breadcrumb-mobile-display and --breadcrumb-desktop-display variables control whether breadcrumbs appear on each device type. By default, they show on both.
Minimal footprint — no shadows, no borders, no heavy decoration. Breadcrumbs should blend into the store's existing design, not compete with it.

Adding JSON-LD Structured Data

Breadcrumbs are one of the most impactful structured data types you can add to a Shopify store. When Google detects valid breadcrumb markup, it can replace the raw URL in search results with a formatted breadcrumb trail — making your listings more readable and clickable.

We'll output JSON-LD structured data alongside the visible breadcrumbs. JSON-LD is Google's preferred format for structured data, and it's cleanly separated from the HTML markup.

Add this right after the closing </nav> tag in breadcrumbs.liquid:

{% comment %} JSON-LD Structured Data {% endcomment %}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": {{ home_text | json }},
      "item": "{{ shop.url }}"
    }

    {% if template.name == 'product' %}
      {% if current_collection %}
        ,{
          "@type": "ListItem",
          "position": 2,
          "name": {{ current_collection.title | json }},
          "item": "{{ shop.url }}{{ current_collection.url }}"
        }
        ,{
          "@type": "ListItem",
          "position": 3,
          "name": {{ product.title | json }}
        }
      {% else %}
        ,{
          "@type": "ListItem",
          "position": 2,
          "name": {{ product.title | json }}
        }
      {% endif %}
    {% endif %}

    {% if template.name == 'collection' %}
      ,{
        "@type": "ListItem",
        "position": 2,
        "name": {{ collection.title | json }}
      }
    {% endif %}

    {% if template.name == 'article' %}
      ,{
        "@type": "ListItem",
        "position": 2,
        "name": {{ blog.title | json }},
        "item": "{{ shop.url }}{{ blog.url }}"
      }
      ,{
        "@type": "ListItem",
        "position": 3,
        "name": {{ article.title | json }}
      }
    {% endif %}

    {% if template.name == 'blog' %}
      ,{
        "@type": "ListItem",
        "position": 2,
        "name": {{ blog.title | json }}
      }
    {% endif %}

    {% if template.name == 'page' %}
      ,{
        "@type": "ListItem",
        "position": 2,
        "name": {{ page.title | json }}
      }
    {% endif %}
  ]
}
</script>

A few important details:

The last item has no item property — per Google's structured data guidelines, the last breadcrumb (the current page) should omit the item URL.
We use the | json Liquid filter to safely escape product and collection titles. This prevents broken JSON when titles contain quotes, ampersands, or other special characters.
shop.url provides the full domain — Shopify's collection.url and blog.url return relative paths (e.g., /collections/shoes), so we prepend shop.url to create fully qualified URLs that search engines expect.

You can validate your structured data using Google's Rich Results Test after deploying.

Making It Configurable from the Theme Editor

Now let's add the {% schema %} block that defines how merchants interact with the breadcrumb settings in the theme editor. This goes at the bottom of breadcrumbs.liquid:

{% schema %}
{
  "name": "Breadcrumbs",
  "target": "section",
  "settings": [
    {
      "type": "text",
      "id": "home_text",
      "label": "Home link text",
      "default": "Home"
    },
    {
      "type": "text",
      "id": "delimiter",
      "label": "Delimiter",
      "default": "/"
    },
    {
      "type": "range",
      "id": "font_size",
      "label": "Font size",
      "min": 10,
      "max": 24,
      "step": 1,
      "default": 14,
      "unit": "px"
    },
    {
      "type": "color",
      "id": "text_color",
      "label": "Current page text color",
      "default": "#666666"
    },
    {
      "type": "color",
      "id": "link_color",
      "label": "Link color",
      "default": "#333333"
    },
    {
      "type": "color",
      "id": "delimiter_color",
      "label": "Delimiter color",
      "default": "#999999"
    },
    {
      "type": "checkbox",
      "id": "show_on_mobile",
      "label": "Show on mobile",
      "default": true
    },
    {
      "type": "checkbox",
      "id": "show_on_desktop",
      "label": "Show on desktop",
      "default": true
    }
  ]
}
{% endschema %}

This schema gives merchants full control over:

Home link text — Some stores prefer "Top" or "Store" instead of "Home"
Delimiter — Choose between /, >, ›, →, or any custom character
Font size — A range slider from 10px to 24px
Colors — Independent control over link color, current page text color, and delimiter color
Responsive visibility — Toggle breadcrumbs on/off for mobile and desktop independently

The "target": "section" property tells Shopify this block can be added to any section in the theme editor — merchants simply click "Add block" and search for "Breadcrumbs."

Complete File

Here's the entire extensions/smart-breadcrumbs/blocks/breadcrumbs.liquid file in one piece. You can copy this directly into your project:

{{ 'breadcrumbs.css' | asset_url | stylesheet_tag }}

{% assign delimiter = block.settings.delimiter %}
{% assign home_text = block.settings.home_text %}

{% comment %} Determine collection context for product pages {% endcomment %}
{% if template.name == 'product' %}
  {% if collection %}
    {% assign current_collection = collection %}
  {% elsif product.collections.size > 0 %}
    {% assign current_collection = product.collections[0] %}
  {% endif %}
{% endif %}

<nav
  class="app-breadcrumbs"
  aria-label="Breadcrumb"
  style="
    --breadcrumb-font-size: {{ block.settings.font_size }}px;
    --breadcrumb-text-color: {{ block.settings.text_color }};
    --breadcrumb-link-color: {{ block.settings.link_color }};
    --breadcrumb-delimiter-color: {{ block.settings.delimiter_color }};
    {% if block.settings.show_on_mobile == false %}
      --breadcrumb-mobile-display: none;
    {% endif %}
    {% if block.settings.show_on_desktop == false %}
      --breadcrumb-desktop-display: none;
    {% endif %}
  "
>
  <ol class="app-breadcrumbs__list">
    {%- comment -%} Home link (always present) {%- endcomment -%}
    <li class="app-breadcrumbs__item">
      <a href="/" class="app-breadcrumbs__link">{{ home_text }}</a>
    </li>

    {%- comment -%} Product pages: Home > Collection > Product {%- endcomment -%}
    {% if template.name == 'product' %}
      {% if current_collection %}
        <li class="app-breadcrumbs__item">
          <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
          <a href="{{ current_collection.url }}" class="app-breadcrumbs__link">
            {{ current_collection.title }}
          </a>
        </li>
      {% endif %}
      <li class="app-breadcrumbs__item app-breadcrumbs__item--current" aria-current="page">
        <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
        <span class="app-breadcrumbs__current">{{ product.title }}</span>
      </li>
    {% endif %}

    {%- comment -%} Collection pages: Home > Collection {%- endcomment -%}
    {% if template.name == 'collection' %}
      <li class="app-breadcrumbs__item app-breadcrumbs__item--current" aria-current="page">
        <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
        <span class="app-breadcrumbs__current">{{ collection.title }}</span>
      </li>
    {% endif %}

    {%- comment -%} Article pages: Home > Blog > Article {%- endcomment -%}
    {% if template.name == 'article' %}
      <li class="app-breadcrumbs__item">
        <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
        <a href="{{ blog.url }}" class="app-breadcrumbs__link">
          {{ blog.title }}
        </a>
      </li>
      <li class="app-breadcrumbs__item app-breadcrumbs__item--current" aria-current="page">
        <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
        <span class="app-breadcrumbs__current">{{ article.title }}</span>
      </li>
    {% endif %}

    {%- comment -%} Blog pages: Home > Blog {%- endcomment -%}
    {% if template.name == 'blog' %}
      <li class="app-breadcrumbs__item app-breadcrumbs__item--current" aria-current="page">
        <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
        <span class="app-breadcrumbs__current">{{ blog.title }}</span>
      </li>
    {% endif %}

    {%- comment -%} Static pages: Home > Page {%- endcomment -%}
    {% if template.name == 'page' %}
      <li class="app-breadcrumbs__item app-breadcrumbs__item--current" aria-current="page">
        <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
        <span class="app-breadcrumbs__current">{{ page.title }}</span>
      </li>
    {% endif %}

    {%- comment -%} Search page: Home > Search {%- endcomment -%}
    {% if template.name == 'search' %}
      <li class="app-breadcrumbs__item app-breadcrumbs__item--current" aria-current="page">
        <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
        <span class="app-breadcrumbs__current">Search</span>
      </li>
    {% endif %}

    {%- comment -%} Cart page: Home > Cart {%- endcomment -%}
    {% if template.name == 'cart' %}
      <li class="app-breadcrumbs__item app-breadcrumbs__item--current" aria-current="page">
        <span class="app-breadcrumbs__delimiter">{{ delimiter }}</span>
        <span class="app-breadcrumbs__current">Cart</span>
      </li>
    {% endif %}
  </ol>
</nav>

{% comment %} JSON-LD Structured Data {% endcomment %}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": {{ home_text | json }},
      "item": "{{ shop.url }}"
    }

    {% if template.name == 'product' %}
      {% if current_collection %}
        ,{
          "@type": "ListItem",
          "position": 2,
          "name": {{ current_collection.title | json }},
          "item": "{{ shop.url }}{{ current_collection.url }}"
        }
        ,{
          "@type": "ListItem",
          "position": 3,
          "name": {{ product.title | json }}
        }
      {% else %}
        ,{
          "@type": "ListItem",
          "position": 2,
          "name": {{ product.title | json }}
        }
      {% endif %}
    {% endif %}

    {% if template.name == 'collection' %}
      ,{
        "@type": "ListItem",
        "position": 2,
        "name": {{ collection.title | json }}
      }
    {% endif %}

    {% if template.name == 'article' %}
      ,{
        "@type": "ListItem",
        "position": 2,
        "name": {{ blog.title | json }},
        "item": "{{ shop.url }}{{ blog.url }}"
      }
      ,{
        "@type": "ListItem",
        "position": 3,
        "name": {{ article.title | json }}
      }
    {% endif %}

    {% if template.name == 'blog' %}
      ,{
        "@type": "ListItem",
        "position": 2,
        "name": {{ blog.title | json }}
      }
    {% endif %}

    {% if template.name == 'page' %}
      ,{
        "@type": "ListItem",
        "position": 2,
        "name": {{ page.title | json }}
      }
    {% endif %}
  ]
}
</script>

{% schema %}
{
  "name": "Breadcrumbs",
  "target": "section",
  "settings": [
    {
      "type": "text",
      "id": "home_text",
      "label": "Home link text",
      "default": "Home"
    },
    {
      "type": "text",
      "id": "delimiter",
      "label": "Delimiter",
      "default": "/"
    },
    {
      "type": "range",
      "id": "font_size",
      "label": "Font size",
      "min": 10,
      "max": 24,
      "step": 1,
      "default": 14,
      "unit": "px"
    },
    {
      "type": "color",
      "id": "text_color",
      "label": "Current page text color",
      "default": "#666666"
    },
    {
      "type": "color",
      "id": "link_color",
      "label": "Link color",
      "default": "#333333"
    },
    {
      "type": "color",
      "id": "delimiter_color",
      "label": "Delimiter color",
      "default": "#999999"
    },
    {
      "type": "checkbox",
      "id": "show_on_mobile",
      "label": "Show on mobile",
      "default": true
    },
    {
      "type": "checkbox",
      "id": "show_on_desktop",
      "label": "Show on desktop",
      "default": true
    }
  ]
}
{% endschema %}

And here's the complete extensions/smart-breadcrumbs/assets/breadcrumbs.css:

.app-breadcrumbs {
  padding: 12px 0;
  font-size: var(--breadcrumb-font-size, 14px);
  color: var(--breadcrumb-text-color, #666);
  line-height: 1.5;
}

.app-breadcrumbs__list {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  list-style: none;
  margin: 0;
  padding: 0;
  gap: 4px;
}

.app-breadcrumbs__item {
  display: flex;
  align-items: center;
  gap: 4px;
}

.app-breadcrumbs__link {
  color: var(--breadcrumb-link-color, #333);
  text-decoration: none;
  transition: opacity 0.2s ease;
}

.app-breadcrumbs__link:hover {
  opacity: 0.7;
  text-decoration: underline;
}

.app-breadcrumbs__delimiter {
  color: var(--breadcrumb-delimiter-color, #999);
  user-select: none;
}

.app-breadcrumbs__current {
  color: var(--breadcrumb-text-color, #666);
}

/* Responsive visibility */
@media screen and (max-width: 749px) {
  .app-breadcrumbs {
    display: var(--breadcrumb-mobile-display, block);
  }
}

@media screen and (min-width: 750px) {
  .app-breadcrumbs {
    display: var(--breadcrumb-desktop-display, block);
  }
}

Things to Watch Out For

Collection Context on Product Pages

The collection Liquid object is only available when a customer navigates to a product from a collection page. If someone lands on a product via a direct link, search, or a product recommendation, collection will be nil. Our code handles this by falling back to product.collections[0], but be aware that the breadcrumb trail might show a different collection than the one the customer expects if the product belongs to multiple collections.

Delimiter Characters and Encoding

Common delimiter choices include /, >, › (single right-pointing angle quotation mark), and →. All of these work fine in both the visible breadcrumbs and JSON-LD. However, if a merchant enters an HTML entity like >, Liquid will output it as the literal string > inside the JSON-LD <script> tag, which is technically valid but messy. Stick to actual characters rather than HTML entities.

JSON-LD Validation

Always test your structured data output with Google's Rich Results Test after deploying. Common issues include:

Missing item property on intermediate breadcrumbs — every breadcrumb except the last one needs a URL
Relative URLs — Google expects fully qualified URLs, which is why we prepend shop.url
Special characters in titles — the | json filter handles this, but double-check with products that have quotes or ampersands in their names

Theme Editor Placement

Merchants should place the breadcrumb block at the top of the page template, typically inside the first section. Since the block uses "target": "section", it can be added to any section — but placement at the top of the main content area is the standard convention for breadcrumbs.

Performance

This implementation requires zero JavaScript — everything is handled by Liquid and CSS. The only assets loaded are a single small CSS file. This means breadcrumbs add virtually no overhead to page load time, which is important for Shopify stores where every millisecond of load time affects conversion rates.

Conclusion

We've built a production-ready breadcrumb navigation block that handles every major Shopify page type, outputs SEO-friendly JSON-LD structured data, and gives merchants full visual control from the theme editor — all without a single line of JavaScript.

The key takeaways:

Theme App Extensions are the cleanest way to deliver UI components to Shopify merchants — no theme code editing, no ScriptTags, no leftovers on uninstall
JSON-LD structured data for breadcrumbs can directly improve how your store appears in Google search results
CSS custom properties are a powerful pattern for passing Liquid settings to stylesheets without JavaScript
Semantic HTML (<nav>, <ol>, aria-label, aria-current) makes breadcrumbs accessible to all users

If you want breadcrumb functionality without building it yourself, check out UR: Smart Breadcrumbs — a no-code solution from UnReact that covers all of this and more.

UR: Smart Breadcrumbs

If you'd rather skip the implementation and add breadcrumbs to your store right away, UR: Smart Breadcrumbs by UnReact is a no-code Shopify app that delivers everything covered in this tutorial — and then some.

Key features:

No-code setup — add breadcrumbs to any Online Store 2.0 theme with one click from the theme editor
Customizable delimiters — choose from common separators or set your own custom character
Full color and typography control — adjust font size, link color, text color, and delimiter color to match your store's design
Responsive visibility toggles — show or hide breadcrumbs independently on mobile and desktop
Home link customization — change the home link text and positioning to fit your store's navigation style
Multi-language support — supports 20+ languages including English, Japanese, French, German, Spanish, and more

It's available on the Shopify App Store with a 7-day free trial.

References

How to Build an Image Slideshow on Shopify Using Theme App Extensions — A Step-by-Step Guide

Eiji Saito — Thu, 25 Jun 2026 00:24:43 +0000

Introduction
What We'll Build
What is a Theme App Extension?
Creating the Extension
Building the Slideshow Markup
Styling the Slideshow
Adding Slide Animation with JavaScript
Supporting Separate Mobile and Desktop Images
Making It Configurable from the Theme Editor
Complete File
Things to Watch Out For
Conclusion
UR: Smart Image Slideshow
References

Introduction

A well-designed image slideshow is one of the most effective ways to showcase products, promotions, or brand stories on a Shopify store. While Shopify themes often include a basic slideshow section, merchants frequently need more control — custom animations, separate mobile/desktop images, and fine-tuned speed settings.

In this tutorial, I'll show you how to build a fully customizable image slideshow as a Shopify app using Theme App Extensions. We'll write real Liquid, CSS, and JavaScript — no theme code editing required, no ScriptTags, and merchants can add the slideshow from the theme editor with zero coding.

By the end, you'll have a working app block that:

Displays a responsive image slideshow with smooth transitions
Supports separate images for PC and mobile
Lets merchants customize animation style, speed, and design from the theme editor
Works across all Online Store 2.0 themes

Let's dive in.

What We'll Build

Here's the final slideshow on a storefront:

Merchants configure it entirely from the theme editor:

What is a Theme App Extension?

Theme App Extensions let Shopify app developers inject UI components — called app blocks — into a merchant's theme without touching the theme's source code.

Why this matters:

No theme code editing — Merchants add your block via the theme editor, just like any native section or block.
Theme-safe — Your code lives inside your app. Theme updates won't break anything.
Uninstall-clean — When a merchant uninstalls your app, all injected blocks are automatically removed. No leftover code.

App blocks are built with Liquid, CSS, and JavaScript — the same stack used in Shopify themes. If you've worked with themes before, you'll feel right at home.

For more details, see the official Shopify documentation on Theme App Extensions.

Creating the Extension

Prerequisites

Make sure you have:

A Shopify Partner account
A development store
Shopify CLI installed
An existing Shopify app (or create one with shopify app init)

Generate the Extension

Inside your app directory, run:

shopify app generate extension --template theme_app_extension --name image-slideshow

This creates the following structure:

extensions/
  image-slideshow/
    blocks/
    assets/
    locales/
    snippets/

Directory Overview

Directory	Purpose
`blocks/`	Liquid files that become app blocks in the theme editor
`assets/`	CSS and JavaScript files
`locales/`	Translation files for multi-language support
`snippets/`	Reusable Liquid snippets

Building the Slideshow Markup

Create the app block at extensions/image-slideshow/blocks/slideshow.liquid:

{{ 'slideshow.css' | asset_url | stylesheet_tag }}

<div
  class="app-slideshow"
  data-speed="{{ block.settings.speed }}"
  data-animation="{{ block.settings.animation }}"
  data-autoplay="{{ block.settings.autoplay }}"
>
  <div class="app-slideshow__track">
    {% for i in (1..5) %}
      {% capture desktop_key %}slide_{{ i }}_desktop{% endcapture %}
      {% capture mobile_key %}slide_{{ i }}_mobile{% endcapture %}
      {% capture link_key %}slide_{{ i }}_link{% endcapture %}

      {% if block.settings[desktop_key] != blank %}
        <div class="app-slideshow__slide" data-index="{{ forloop.index0 }}">
          {% if block.settings[link_key] != blank %}
            <a href="{{ block.settings[link_key] }}" class="app-slideshow__link">
          {% endif %}

          {%- comment -%} Desktop image {%- endcomment -%}
          <picture>
            {% if block.settings[mobile_key] != blank %}
              <source
                media="(max-width: 749px)"
                srcset="{{ block.settings[mobile_key] | image_url: width: 750 }}"
              >
            {% endif %}
            <img
              class="app-slideshow__image"
              src="{{ block.settings[desktop_key] | image_url: width: 1500 }}"
              alt="{{ block.settings[desktop_key].alt | escape }}"
              loading="{% if forloop.first %}eager{% else %}lazy{% endif %}"
              width="1500"
              height="750"
            >
          </picture>

          {% if block.settings[link_key] != blank %}
            </a>
          {% endif %}
        </div>
      {% endif %}
    {% endfor %}
  </div>

  {%- comment -%} Navigation dots {%- endcomment -%}
  <div class="app-slideshow__dots"></div>

  {%- comment -%} Previous / Next arrows {%- endcomment -%}
  <button class="app-slideshow__arrow app-slideshow__arrow--prev" aria-label="Previous slide">
    &#10094;
  </button>
  <button class="app-slideshow__arrow app-slideshow__arrow--next" aria-label="Next slide">
    &#10095;
  </button>
</div>

{{ 'slideshow.js' | asset_url | script_tag }}

A few things to note:

We use the <picture> element to serve different images for mobile and desktop
The first slide uses loading="eager" for performance; subsequent slides use lazy
Navigation dots are generated dynamically by JavaScript
Data attributes pass merchant settings to JavaScript

Styling the Slideshow

Create extensions/image-slideshow/assets/slideshow.css:

.app-slideshow {
  position: relative;
  overflow: hidden;
  width: 100%;
  max-width: 100%;
}

.app-slideshow__track {
  display: flex;
  transition: transform 0.5s ease-in-out;
  will-change: transform;
}

.app-slideshow__slide {
  min-width: 100%;
  flex-shrink: 0;
}

.app-slideshow__image {
  display: block;
  width: 100%;
  height: auto;
  object-fit: cover;
}

.app-slideshow__link {
  display: block;
}

/* Arrows */
.app-slideshow__arrow {
  position: absolute;
  top: 50%;
  transform: translateY(-50%);
  background: rgba(0, 0, 0, 0.4);
  color: #fff;
  border: none;
  font-size: 24px;
  padding: 12px 16px;
  cursor: pointer;
  z-index: 2;
  border-radius: 4px;
  transition: background 0.2s;
}

.app-slideshow__arrow:hover {
  background: rgba(0, 0, 0, 0.7);
}

.app-slideshow__arrow--prev {
  left: 12px;
}

.app-slideshow__arrow--next {
  right: 12px;
}

/* Dots */
.app-slideshow__dots {
  display: flex;
  justify-content: center;
  gap: 8px;
  padding: 12px 0;
}

.app-slideshow__dot {
  width: 10px;
  height: 10px;
  border-radius: 50%;
  border: none;
  background: rgba(0, 0, 0, 0.3);
  cursor: pointer;
  padding: 0;
  transition: background 0.2s;
}

.app-slideshow__dot.is-active {
  background: rgba(0, 0, 0, 0.8);
}

/* Fade animation variant */
.app-slideshow[data-animation="fade"] .app-slideshow__track {
  display: block;
  position: relative;
}

.app-slideshow[data-animation="fade"] .app-slideshow__slide {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  opacity: 0;
  transition: opacity 0.6s ease-in-out;
}

.app-slideshow[data-animation="fade"] .app-slideshow__slide:first-child {
  position: relative;
}

.app-slideshow[data-animation="fade"] .app-slideshow__slide.is-active {
  opacity: 1;
  z-index: 1;
}

This gives us two animation styles:

Slide (default) — slides move horizontally using transform: translateX()
Fade — slides crossfade using opacity transitions

Adding Slide Animation with JavaScript

Create extensions/image-slideshow/assets/slideshow.js:

(function () {
  function initSlideshow(container) {
    const track = container.querySelector('.app-slideshow__track');
    const slides = container.querySelectorAll('.app-slideshow__slide');
    const dotsContainer = container.querySelector('.app-slideshow__dots');
    const prevBtn = container.querySelector('.app-slideshow__arrow--prev');
    const nextBtn = container.querySelector('.app-slideshow__arrow--next');

    if (!track || slides.length === 0) return;

    const speed = parseInt(container.dataset.speed, 10) || 5000;
    const animation = container.dataset.animation || 'slide';
    const autoplay = container.dataset.autoplay === 'true';
    const totalSlides = slides.length;
    let currentIndex = 0;
    let autoplayTimer = null;

    // Generate dots
    dotsContainer.innerHTML = '';
    slides.forEach(function (_, index) {
      const dot = document.createElement('button');
      dot.classList.add('app-slideshow__dot');
      dot.setAttribute('aria-label', 'Go to slide ' + (index + 1));
      if (index === 0) dot.classList.add('is-active');
      dot.addEventListener('click', function () {
        goToSlide(index);
      });
      dotsContainer.appendChild(dot);
    });

    const dots = dotsContainer.querySelectorAll('.app-slideshow__dot');

    function goToSlide(index) {
      currentIndex = index;

      if (animation === 'fade') {
        slides.forEach(function (slide, i) {
          slide.classList.toggle('is-active', i === currentIndex);
        });
      } else {
        track.style.transform = 'translateX(-' + (currentIndex * 100) + '%)';
      }

      dots.forEach(function (dot, i) {
        dot.classList.toggle('is-active', i === currentIndex);
      });

      resetAutoplay();
    }

    function nextSlide() {
      goToSlide((currentIndex + 1) % totalSlides);
    }

    function prevSlide() {
      goToSlide((currentIndex - 1 + totalSlides) % totalSlides);
    }

    function resetAutoplay() {
      if (!autoplay) return;
      clearInterval(autoplayTimer);
      autoplayTimer = setInterval(nextSlide, speed);
    }

    // Arrow buttons
    prevBtn.addEventListener('click', prevSlide);
    nextBtn.addEventListener('click', nextSlide);

    // Touch / swipe support
    let touchStartX = 0;
    let touchEndX = 0;

    container.addEventListener('touchstart', function (e) {
      touchStartX = e.changedTouches[0].screenX;
    }, { passive: true });

    container.addEventListener('touchend', function (e) {
      touchEndX = e.changedTouches[0].screenX;
      var diff = touchStartX - touchEndX;
      if (Math.abs(diff) > 50) {
        if (diff > 0) {
          nextSlide();
        } else {
          prevSlide();
        }
      }
    }, { passive: true });

    // Initialize first slide for fade animation
    if (animation === 'fade') {
      slides[0].classList.add('is-active');
    }

    // Start autoplay
    if (autoplay) {
      autoplayTimer = setInterval(nextSlide, speed);
    }

    // Hide arrows if single slide
    if (totalSlides <= 1) {
      prevBtn.style.display = 'none';
      nextBtn.style.display = 'none';
      dotsContainer.style.display = 'none';
    }
  }

  function initAll() {
    document.querySelectorAll('.app-slideshow').forEach(initSlideshow);
  }

  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', initAll);
  } else {
    initAll();
  }

  // Re-initialize on theme editor section reload
  document.addEventListener('shopify:section:load', initAll);
})();

Key features:

Two animation modes — slide (translateX) and fade (opacity)
Autoplay with configurable speed
Touch/swipe support for mobile devices
Navigation dots generated dynamically from the slide count
Theme editor compatible — re-initializes on shopify:section:load

Supporting Separate Mobile and Desktop Images

One of the most requested features for store slideshows is the ability to set different images for PC and mobile. Banner images designed for wide desktop screens often look terrible on narrow mobile viewports — text gets too small, the composition breaks, and the impact is lost.

We handle this with the <picture> element:

<picture>
  {% if block.settings[mobile_key] != blank %}
    <source
      media="(max-width: 749px)"
      srcset="{{ block.settings[mobile_key] | image_url: width: 750 }}"
    >
  {% endif %}
  <img
    src="{{ block.settings[desktop_key] | image_url: width: 1500 }}"
    alt="{{ block.settings[desktop_key].alt | escape }}"
  >
</picture>

How it works:

On screens 749px and below (mobile), the browser loads the mobile image
On screens 750px and above (desktop/tablet), the desktop image is used
If no mobile image is set, the desktop image is used as a fallback

This approach is better than using CSS display: none because the browser only downloads the image it actually needs — saving bandwidth on mobile.

Making It Configurable from the Theme Editor

The schema at the bottom of the Liquid file defines what merchants see in the theme editor. Add the following at the very end of slideshow.liquid, after the {{ 'slideshow.js' | asset_url | script_tag }} line:

{% schema %}
{
  "name": "Image Slideshow",
  "target": "section",
  "settings": [
    {
      "type": "select",
      "id": "animation",
      "label": "Animation style",
      "options": [
        { "value": "slide", "label": "Slide" },
        { "value": "fade", "label": "Fade" }
      ],
      "default": "slide"
    },
    {
      "type": "range",
      "id": "speed",
      "label": "Autoplay speed (ms)",
      "min": 2000,
      "max": 10000,
      "step": 500,
      "default": 5000,
      "unit": "ms"
    },
    {
      "type": "checkbox",
      "id": "autoplay",
      "label": "Enable autoplay",
      "default": true
    },
    {
      "type": "header",
      "content": "Slide 1"
    },
    {
      "type": "image_picker",
      "id": "slide_1_desktop",
      "label": "Desktop image"
    },
    {
      "type": "image_picker",
      "id": "slide_1_mobile",
      "label": "Mobile image (optional)"
    },
    {
      "type": "url",
      "id": "slide_1_link",
      "label": "Link URL (optional)"
    },
    {
      "type": "header",
      "content": "Slide 2"
    },
    {
      "type": "image_picker",
      "id": "slide_2_desktop",
      "label": "Desktop image"
    },
    {
      "type": "image_picker",
      "id": "slide_2_mobile",
      "label": "Mobile image (optional)"
    },
    {
      "type": "url",
      "id": "slide_2_link",
      "label": "Link URL (optional)"
    },
    {
      "type": "header",
      "content": "Slide 3"
    },
    {
      "type": "image_picker",
      "id": "slide_3_desktop",
      "label": "Desktop image"
    },
    {
      "type": "image_picker",
      "id": "slide_3_mobile",
      "label": "Mobile image (optional)"
    },
    {
      "type": "url",
      "id": "slide_3_link",
      "label": "Link URL (optional)"
    },
    {
      "type": "header",
      "content": "Slide 4"
    },
    {
      "type": "image_picker",
      "id": "slide_4_desktop",
      "label": "Desktop image"
    },
    {
      "type": "image_picker",
      "id": "slide_4_mobile",
      "label": "Mobile image (optional)"
    },
    {
      "type": "url",
      "id": "slide_4_link",
      "label": "Link URL (optional)"
    },
    {
      "type": "header",
      "content": "Slide 5"
    },
    {
      "type": "image_picker",
      "id": "slide_5_desktop",
      "label": "Desktop image"
    },
    {
      "type": "image_picker",
      "id": "slide_5_mobile",
      "label": "Mobile image (optional)"
    },
    {
      "type": "url",
      "id": "slide_5_link",
      "label": "Link URL (optional)"
    }
  ],
  "presets": [
    {
      "name": "Image Slideshow"
    }
  ]
}
{% endschema %}

This gives merchants full control over:

Animation style — slide or fade
Autoplay speed — 2 to 10 seconds with a range slider
Autoplay toggle — on/off
Up to 5 slides, each with desktop image, mobile image, and optional link URL

Complete File

Here is the complete slideshow.liquid file with markup and schema combined. You can copy this directly into extensions/image-slideshow/blocks/slideshow.liquid:

{{ 'slideshow.css' | asset_url | stylesheet_tag }}

<div
  class="app-slideshow"
  data-speed="{{ block.settings.speed }}"
  data-animation="{{ block.settings.animation }}"
  data-autoplay="{{ block.settings.autoplay }}"
>
  <div class="app-slideshow__track">
    {% for i in (1..5) %}
      {% capture desktop_key %}slide_{{ i }}_desktop{% endcapture %}
      {% capture mobile_key %}slide_{{ i }}_mobile{% endcapture %}
      {% capture link_key %}slide_{{ i }}_link{% endcapture %}

      {% if block.settings[desktop_key] != blank %}
        <div class="app-slideshow__slide" data-index="{{ forloop.index0 }}">
          {% if block.settings[link_key] != blank %}
            <a href="{{ block.settings[link_key] }}" class="app-slideshow__link">
          {% endif %}

          <picture>
            {% if block.settings[mobile_key] != blank %}
              <source
                media="(max-width: 749px)"
                srcset="{{ block.settings[mobile_key] | image_url: width: 750 }}"
              >
            {% endif %}
            <img
              class="app-slideshow__image"
              src="{{ block.settings[desktop_key] | image_url: width: 1500 }}"
              alt="{{ block.settings[desktop_key].alt | escape }}"
              loading="{% if forloop.first %}eager{% else %}lazy{% endif %}"
              width="1500"
              height="750"
            >
          </picture>

          {% if block.settings[link_key] != blank %}
            </a>
          {% endif %}
        </div>
      {% endif %}
    {% endfor %}
  </div>

  <div class="app-slideshow__dots"></div>

  <button class="app-slideshow__arrow app-slideshow__arrow--prev" aria-label="Previous slide">
    &#10094;
  </button>
  <button class="app-slideshow__arrow app-slideshow__arrow--next" aria-label="Next slide">
    &#10095;
  </button>
</div>

{{ 'slideshow.js' | asset_url | script_tag }}

{% schema %}
{
  "name": "Image Slideshow",
  "target": "section",
  "settings": [
    {
      "type": "select",
      "id": "animation",
      "label": "Animation style",
      "options": [
        { "value": "slide", "label": "Slide" },
        { "value": "fade", "label": "Fade" }
      ],
      "default": "slide"
    },
    {
      "type": "range",
      "id": "speed",
      "label": "Autoplay speed (ms)",
      "min": 2000,
      "max": 10000,
      "step": 500,
      "default": 5000,
      "unit": "ms"
    },
    {
      "type": "checkbox",
      "id": "autoplay",
      "label": "Enable autoplay",
      "default": true
    },
    {
      "type": "header",
      "content": "Slide 1"
    },
    {
      "type": "image_picker",
      "id": "slide_1_desktop",
      "label": "Desktop image"
    },
    {
      "type": "image_picker",
      "id": "slide_1_mobile",
      "label": "Mobile image (optional)"
    },
    {
      "type": "url",
      "id": "slide_1_link",
      "label": "Link URL (optional)"
    },
    {
      "type": "header",
      "content": "Slide 2"
    },
    {
      "type": "image_picker",
      "id": "slide_2_desktop",
      "label": "Desktop image"
    },
    {
      "type": "image_picker",
      "id": "slide_2_mobile",
      "label": "Mobile image (optional)"
    },
    {
      "type": "url",
      "id": "slide_2_link",
      "label": "Link URL (optional)"
    },
    {
      "type": "header",
      "content": "Slide 3"
    },
    {
      "type": "image_picker",
      "id": "slide_3_desktop",
      "label": "Desktop image"
    },
    {
      "type": "image_picker",
      "id": "slide_3_mobile",
      "label": "Mobile image (optional)"
    },
    {
      "type": "url",
      "id": "slide_3_link",
      "label": "Link URL (optional)"
    },
    {
      "type": "header",
      "content": "Slide 4"
    },
    {
      "type": "image_picker",
      "id": "slide_4_desktop",
      "label": "Desktop image"
    },
    {
      "type": "image_picker",
      "id": "slide_4_mobile",
      "label": "Mobile image (optional)"
    },
    {
      "type": "url",
      "id": "slide_4_link",
      "label": "Link URL (optional)"
    },
    {
      "type": "header",
      "content": "Slide 5"
    },
    {
      "type": "image_picker",
      "id": "slide_5_desktop",
      "label": "Desktop image"
    },
    {
      "type": "image_picker",
      "id": "slide_5_mobile",
      "label": "Mobile image (optional)"
    },
    {
      "type": "url",
      "id": "slide_5_link",
      "label": "Link URL (optional)"
    }
  ],
  "presets": [
    {
      "name": "Image Slideshow"
    }
  ]
}
{% endschema %}

Things to Watch Out For

1. Performance and Image Optimization

Large slideshow images can seriously hurt page load times. Follow these best practices:

Use Shopify's image_url filter with a width parameter — this serves optimally sized images through Shopify's CDN
Set loading="lazy" on all slides except the first one
Keep image file sizes reasonable (compress before uploading)

2. Theme Compatibility

App blocks work with Online Store 2.0 themes only. Older "vintage" themes do not support app blocks. Most themes in the Shopify Theme Store today are OS 2.0, but it's worth noting in your app's documentation.

Additionally, each theme has different section structures. Test your slideshow against:

Dawn (Shopify's default free theme)
At least 2-3 popular paid themes

3. Accessibility

Make sure your slideshow is accessible:

Include aria-label attributes on navigation buttons (we did this)
Provide meaningful alt text on images — this comes from the merchant's image upload
Consider adding aria-live="polite" to announce slide changes to screen readers
Ensure arrow buttons and dots are keyboard-navigable

4. Autoplay Considerations

While autoplay makes slideshows dynamic, some users find auto-advancing slides frustrating. Consider:

Making autoplay off by default and letting merchants opt in
Pausing autoplay when the user hovers over the slideshow
Respecting the prefers-reduced-motion media query:

const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
if (prefersReducedMotion) {
  // Disable autoplay and use instant transitions
}

Conclusion

In this tutorial, we built a fully customizable image slideshow for Shopify stores using Theme App Extensions. Here's what we covered:

Created a Theme App Extension with Shopify CLI
Built a responsive slideshow with Liquid, CSS, and JavaScript
Added slide and fade animations with touch/swipe support
Supported separate PC and mobile images using the <picture> element
Made everything configurable from the theme editor — no code required for merchants

Theme App Extensions are a powerful pattern for building storefront features. Once you understand the approach, you can apply it to all kinds of UI components — countdown timers, custom badges, product tabs, and more.

If you're looking for a production-ready slideshow without building from scratch, we develop Shopify apps at UnReact that use this exact same Theme App Extension architecture. Our UR: Smart Image Slideshow provides a no-code image slider with customizable animations, speed control, and separate mobile/desktop image support — all configurable from the theme editor.

Feel free to drop a comment below if you have questions. Happy building!

UR: Smart Image Slideshow

If you want a production-ready image slideshow without building one from scratch, check out our Shopify app:

👉 UR: Smart Image Slideshow

Built by UnReact, this app uses the exact same Theme App Extension architecture covered in this tutorial. It provides:

No-code setup — add a fully customizable slideshow from the theme editor
Slide & fade animations with adjustable speed
Separate PC and mobile images for optimized responsive design
Up to 10 slides with optional link URLs
Works with all Online Store 2.0 themes

Install it in one click and start showcasing your products, promotions, and brand stories with a beautiful image slider — no coding required.

DEV Community: Eiji Saito

How to Build a Cart Upsell Widget for Shopify with the Ajax Cart API

Table of Contents

Introduction

What We'll Build

How Cart Upsell Widgets Work

Product Recommendations API

Cart Ajax API

Putting It Together

Setting Up the Theme App Extension

Prerequisites

Generate the Extension

Fetching Cart Data and Recommended Products

Reading the Cart

Picking a Reference Product

Fetching Recommendations

Filtering and Limiting

Building the Liquid Template

Schema

Styling the Upsell Widget

Adding Products to the Cart from the Widget

Complete File

Tips and Common Pitfalls

Recommendations API Prices Are Not in Cents

Empty Recommendations Are Normal

intent=complementary Needs Configuration

Not All Themes Dispatch the Same Cart Events

Debounce If You Add Quantity-Watching

Cart Drawer vs. Cart Page Placement

Conclusion

References

How to Embed YouTube Videos in Shopify Without Killing Your Page Speed

Table of Contents

Introduction

What We'll Build

Why a Plain YouTube iframe Hurts Your Store

The Facade Pattern Explained

Setting Up the Theme App Extension

Parsing the YouTube URL with Liquid

Guarding against an empty URL

Building the thumbnail URL

Building the Facade Markup

Styling a Responsive 16:9 Player

Swapping in the Real iframe with JavaScript

Making It Configurable from the Theme Editor

Complete File

extensions/youtube-embed/blocks/youtube-embed.liquid

extensions/youtube-embed/assets/youtube-embed.css

extensions/youtube-embed/assets/youtube-embed.js

Tips and Common Pitfalls

Conclusion

UR: Smart YouTube Embed

References

How to Build a Sticky Add-to-Cart Bar in Shopify with Liquid and JavaScript

Table of Contents

Introduction

What We'll Build

How Sticky Cart Bars Work

1. Visibility Trigger

2. Fixed Positioning

3. Cart Submission

Setting Up the Theme App Extension

Prerequisites

Generate the Extension

Building the Liquid Template

The Sticky Bar Container

Product Information

Variant Selector

Styling the Sticky Bar

Adding JavaScript for Show/Hide Logic

Handling Variant Selection

Complete File

Tips and Common Pitfalls

Z-index Conflicts

Mobile Bottom Navigation

Cart Drawer Integration

Accessibility

Performance

Conclusion

UR: Smart Sticky Cart

`intent=complementary` Needs Configuration

`extensions/youtube-embed/blocks/youtube-embed.liquid`

`extensions/youtube-embed/assets/youtube-embed.css`

`extensions/youtube-embed/assets/youtube-embed.js`