> For the complete documentation index, see [llms.txt](https://docs.elitebundleapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elitebundleapp.com/guides/custom-ui.md).

# Custom bundle UI

Step-by-step guide to replacing the built-in Build Your Own Bundle UI on Shopify with your own HTML, powered by the Elite Bundle Builder SDK.

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.

```html
<!-- _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.

```js
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

`sdk.steps` holds only the steps showing right now: a step with a **Show this step** rule appears once the shopper picks what it waits for, or sits there with `locked: true` until then (grey it out; `canAddToStep` is already `false`). So the render function below clears and rebuilds, and step 4 calls it again when the step ids change.

```js
let renderedSteps = '';

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');
  stepsContainer.innerHTML = '';
  renderedSteps = sdk.steps.map(step => step.id).join();

  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;
        card.dataset.price = variant.price;
        card.dataset.available = variant.available;

        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.

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

  // A pick can show or hide a step: rebuild when the steps change.
  if (sdk.steps.map(step => step.id).join() !== renderedSteps) initMyBundleUI();

  // 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;

    // The price matters for amount limits: a $30 item may not fit where a $10 one does.
    const canAdd = sdk.canAddToStep(stepId, parseFloat(card.dataset.price));
    addBtn.disabled = !canAdd || card.dataset.available !== 'true';
    card.querySelector('.qty-inc').disabled = !canAdd;
  });
});
```

***

## 5. Handle checkout

```js
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)

```js
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

```js
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:

```js
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.

```js
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.

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

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

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