Custom Bundle UI

This guide walks through building a fully custom Build Your Own Bundle UI from scratch, using the Elite Bundle Builder SDK for data and actions while rendering your own HTML.

The built-in UI continues to work — you can replace individual parts or the whole thing.

---

Prerequisites

• SDK access enabled in App → Settings → Developer SDK
• A bundle product set up with at least one step
• Access to your Shopify theme files

---

1. Add your HTML scaffold

In your theme, add the container elements where your custom bundle UI will render. Place these on the bundle product page — either in the product template or a theme section.

<!-- _theme/sections/custom-byob.liquid or similar -->
<div id="my-bundle-root" style="display: none;">
  <div id="my-steps"></div>
  <div id="my-cart-drawer">
    <ul id="my-cart-items"></ul>
    <p>Total: <span id="my-cart-total">$0.00</span></p>
    <button id="my-checkout-btn" disabled>Checkout</button>
  </div>
</div>
<div id="my-bundle-loading">Loading bundle…</div>
<div id="my-bundle-error" style="display: none;"></div>

---

2. Wait for the SDK to be ready

The SDK populates window.eliteBundle.sdk.byob after React mounts and products load. Listen for the ready event before reading any state.

function onByobReady(callback) {
  if (!window.eliteBundle?.sdk) return; // SDK not enabled, abort

  document.addEventListener('elite:byob:ready', callback);

  // Handle the case where ready fired before this script loaded
  const sdk = window.eliteBundle.sdk.byob;
  if (sdk && !sdk.isLoading && !sdk.error) callback();
}

onByobReady(initMyBundleUI);

---

3. Render steps and products

function initMyBundleUI() {
  const sdk = window.eliteBundle.sdk.byob;

  document.querySelector('#my-bundle-loading').style.display = 'none';
  document.querySelector('#my-bundle-root').style.display = '';

  const stepsContainer = document.querySelector('#my-steps');

  sdk.steps.forEach(step => {
    const stepEl = document.createElement('div');
    stepEl.className = 'bundle-step';
    // Titles can be translated, so resolve before rendering (see below).
    stepEl.innerHTML = `<h2>${text(step.title)}</h2>`;

    // Add a products grid
    const grid = document.createElement('div');
    grid.className = 'products-grid';

    step.products.forEach(product => {
      product.variants.forEach(variant => {
        const card = document.createElement('div');
        card.className = 'product-card';
        card.dataset.variantId = variant.id;
        card.dataset.stepId = step.id;

        const image = product.featuredImage?.url ?? '';
        const price = sdk.formatPrice(parseFloat(variant.price));

        card.innerHTML = `
          <img src="${image}" alt="${product.title}" />
          <p class="product-title">${product.title}</p>
          ${variant.title !== 'Default Title' ? `<p class="variant-title">${variant.title}</p>` : ''}
          <p class="price">${price}</p>
          <div class="qty-controls" style="display: none;">
            <button class="qty-dec">−</button>
            <span class="qty-display">0</span>
            <button class="qty-inc">+</button>
          </div>
          <button class="add-btn" ${!variant.available ? 'disabled' : ''}>
            ${variant.available ? 'Add' : 'Sold out'}
          </button>
        `;

        // Add to cart
        card.querySelector('.add-btn').addEventListener('click', () => {
          sdk.addToCart(product, variant.id, step.id);
        });

        // Quantity controls
        card.querySelector('.qty-inc').addEventListener('click', () => {
          sdk.updateQuantity(variant.id, 1, step.id);
        });
        card.querySelector('.qty-dec').addEventListener('click', () => {
          sdk.updateQuantity(variant.id, -1, step.id);
        });

        grid.appendChild(card);
      });
    });

    stepEl.appendChild(grid);
    stepsContainer.appendChild(stepEl);
  });
}

---

4. Keep the cart in sync

Listen for elite:byob:cart-change to update your UI after every cart mutation.

document.addEventListener('elite:byob:cart-change', (event) => {
  const { cart, cartTotal, cartCount, canCheckout } = event.detail;
  const sdk = window.eliteBundle.sdk.byob;

  // Update total and checkout button
  // The detail carries the raw number — format it for display.
  document.querySelector('#my-cart-total').textContent =
    window.eliteBundle.sdk.byob.formatPrice(cartTotal);
  document.querySelector('#my-checkout-btn').disabled = !canCheckout;

  // Update cart items list
  const itemsList = document.querySelector('#my-cart-items');
  itemsList.innerHTML = '';
  cart.forEach(item => {
    const li = document.createElement('li');
    li.textContent = `${item.title} × ${item.quantity} — ${sdk.formatPrice(item.price * item.quantity)}`;
    itemsList.appendChild(li);
  });

  // Update per-card quantity displays and step limits
  document.querySelectorAll('.product-card').forEach(card => {
    const variantId = card.dataset.variantId;
    const stepId = card.dataset.stepId;
    const qty = sdk.getItemQuantity(variantId, stepId);

    const qtyControls = card.querySelector('.qty-controls');
    const addBtn = card.querySelector('.add-btn');
    const qtyDisplay = card.querySelector('.qty-display');

    qtyControls.style.display = qty > 0 ? '' : 'none';
    qtyDisplay.textContent = qty;

    const stepFull = sdk.isStepFull(stepId);
    addBtn.disabled = stepFull && qty === 0;
  });
});

---

5. Handle checkout

const checkoutBtn = document.querySelector('#my-checkout-btn');

checkoutBtn.addEventListener('click', () => {
  window.eliteBundle.sdk.byob.checkout('checkout');
});

// Loading state while checkout is in flight
document.addEventListener('elite:byob:checkout-start', () => {
  checkoutBtn.textContent = 'Processing…';
  checkoutBtn.disabled = true;
});

document.addEventListener('elite:byob:checkout-error', (event) => {
  checkoutBtn.textContent = 'Checkout';
  checkoutBtn.disabled = false;
  alert('Checkout failed: ' + event.detail.error);
});

---

6. Show a discount tier indicator (optional)

function renderTierProgress() {
  const { discountConfig, cartCount, isTierMaxReached } = window.eliteBundle.sdk.byob;

  if (discountConfig.discountType !== 'tier') return;

  const tiers = discountConfig.tiers;
  // Thresholds are `minValue`, and they measure the cart TOTAL when
  // tierBasedOn is "order_total" rather than the item count.
  const basis = discountConfig.tierBasedOn === 'order_total' ? cartTotal : cartCount;
  const nextTier = [...tiers]
    .sort((a, b) => a.minValue - b.minValue)
    .find(t => t.minValue > basis);

  const progressEl = document.querySelector('#discount-progress');

  if (isTierMaxReached || !nextTier) {
    progressEl.textContent = `Maximum discount applied!`;
    return;
  }

  const remaining = nextTier.minValue - basis;
  progressEl.textContent =
    `Add ${remaining} more item${remaining !== 1 ? 's' : ''} for ${nextTier.discountValue}% off`;
}

document.addEventListener('elite:byob:cart-change', renderTierProgress);

---

7. Handle errors

document.addEventListener('elite:byob:error', (event) => {
  document.querySelector('#my-bundle-loading').style.display = 'none';
  const errorEl = document.querySelector('#my-bundle-error');
  errorEl.textContent = 'Failed to load bundle: ' + event.detail.error;
  errorEl.style.display = '';
});

---

Resolving translated text

Step titles and descriptions are either a plain string or a translated object, so resolve them before rendering:

function text(value, locale = document.documentElement.lang) {
  if (typeof value === 'string') return value;
  return value?.translations?.[locale] ?? value?.default ?? '';
}

Multi-option bundles

A multi-option bundle uses this same SDK — its options arrive as steps, and each holds exactly one item. The one difference is how you record a pick: use selectOne instead of addToCart, so choosing a different item replaces the option's current pick rather than stacking a second one.

document.addEventListener('elite:byob:ready', () => {
  const sdk = window.eliteBundle.sdk?.byob;
  if (!sdk) return;

  sdk.steps.forEach((option) => {
    const el = document.querySelector(`#option-${option.id}`);
    el.querySelector('h3').textContent = text(option.title);

    option.products.forEach((product) => {
      product.variants.forEach((variant) => {
        const chip = document.createElement('button');
        chip.textContent = `${product.title} — ${sdk.formatPrice(Number(variant.price))}`;
        chip.disabled = !variant.available;
        chip.addEventListener('click', () => {
          sdk.selectOne(product, variant.id, option.id);
        });
        el.appendChild(chip);
      });
    });
  });
});

Adding to cart differs too: a multi-option bundle hooks the theme's own Add to cart button, so you normally do not call checkout() yourself. Gate on canCheckout to know when every option has been filled.

Hiding the default UI

If you want to replace (not augment) the built-in UI, hide it with CSS. The bundle renders inside a [data-byob-bundle] element.

On a bundle that renders inside the theme's product page, the app also hides the theme's own price and add-to-cart button. Hiding [data-byob-bundle] there leaves the page with no way to buy, so your replacement UI must supply its own add-to-cart.

/* In your theme CSS */
[data-byob-bundle] {
  display: none !important;
}

Or hide it in JavaScript after the ready event, so there's no flash:

document.addEventListener('elite:byob:ready', () => {
  const defaultUI = document.querySelector('[data-byob-bundle]');
  if (defaultUI) defaultUI.style.display = 'none';
});