@lime-bundles/widget

Drop-in <lime-bundle> web component for the Lime Bundles Shopify app. Embed merchant-configured bundles on any JavaScript-enabled headless storefront (Hydrogen, Astro, Vue, Svelte, plain HTML). If you're not a merchant using Lime Bundles, this package probably isn't what you're looking for.

Ships the full widget your merchants see in the admin preview: header, save badge, product list with count bubbles, savings bar, pricing footer, themed CTA.

Install

Via npm:

npm install @lime-bundles/widget

import "@lime-bundles/widget"; // registers <lime-bundle> globally

Or via CDN, zero build step:

<script type="module" src="https://unpkg.com/@lime-bundles/widget"></script>

Paste-and-go

One snippet in your product page template. The widget resolves the current product from the URL (/products/<handle>) and renders every active bundle configured for it. Clicking Add bundle calls Shopify's tokenless Storefront Cart API and redirects to checkout with the discount applied.

<script type="module" src="https://unpkg.com/@lime-bundles/widget"></script>
<lime-bundle
  shop-domain="my-shop.myshopify.com"
  storefront-token="<YOUR_LIME_BUNDLES_TOKEN>"
></lime-bundle>

Generate the token at /app/settings/headless in your Lime Bundles admin. It's a read-only Storefront Access Token (bundle metaobjects + product listings only), safe to ship in HTML.

BYO cart

Listen for lime-bundle:add-to-cart and call event.preventDefault() to suppress the default redirect:

document.querySelector("lime-bundle").addEventListener(
  "lime-bundle:add-to-cart",
  async (event) => {
    event.preventDefault();
    await myCart.linesAdd(event.detail.lines);
  },
);

Attributes

| Attribute | Required | Purpose | |---|:-:|---| | shop-domain | ✓ | *.myshopify.com domain. | | storefront-token | ✓ | Storefront Access Token from /app/settings/headless. | | bundle-gid | | Render one specific bundle. Overrides auto-detect. | | product-handle | | Render bundles for this handle. Overrides URL detection. | | product-id | | The product this embed is standing on — full GID or bare numeric id. Volume bundles price and sell this product; falls back to the handle cascade, then the bundle's first product. | | app-url | | Enables impression + add-to-cart analytics when set. | | analytics | | "false" suppresses analytics even when app-url is set. | | locale | | BCP-47 tag forwarded to the Storefront API. | | country | | ISO-3166 alpha-2 (e.g. "US"). Adds @inContext(country:) to Storefront queries — Markets pricing + currency — and matches market-restricted bundles' projected country codes. | | language | | ISO-639-1 (e.g. "EN"). Adds @inContext(language:). | | market-id | | Current visitor's Market GID. Legacy market-gate signal; prefer country (retail) and the buyer property (B2B) — a B2B buyer's company-location market has no storefront market context. | | currency-rate | | Store→presentment currency rate. Merchant-configured amounts (fixed-amount discounts, flat prices, volume tier amounts) are stored in the shop's store currency; on a "local currencies" market, pass the buyer's rate (on a Liquid-adjacent page, window.Shopify.currency.rate) so quoted sale prices match what checkout charges. Defaults to 1 (no conversion); invalid or non-positive values also fall back to 1. Percentages are unaffected. |

A market-restricted bundle renders when any signal matches: country vs the bundle's projected country codes, the resolved buyer property's companyLocationId vs its projected company locations, or market-id vs its market allow-list.

Product resolution (when bundle-gid is absent): explicit product-handle → <meta name="shopify:product-handle"> → /products/<handle> URL segment.

Multi-product binding: a volume bundle can span several products, and the widget prices and sells the one the shopper is looking at: explicit product-id → the handle cascade above → the bundle's first product. On a pinned bundle-gid embed outside a /products/<handle> URL, set product-id (or product-handle) or the first product is what gets sold.

Changing any attribute at runtime re-fetches and re-renders.

B2B buyer identity (programmatic property only)

buyer is not an HTML attribute. Set it on the element after creation so the customer access token never lands in DOM-snapshot tools (Sentry, analytics, browser extensions) or Referer headers:

const el = document.querySelector("lime-bundle");
el.buyer = async () => {
  // Resolved per request — no token in static markup
  return { customerAccessToken: await fetchToken(), companyLocationId: "gid://shopify/CompanyLocation/9" };
};

The Customer Account API PKCE flow is the canonical token source. See https://shopify.dev/docs/api/customer/latest.

Buyer-contextual Storefront responses MUST be Cache-Control: private — never share across users.

Events

All events bubble and pierce shadow-DOM boundaries (composed: true), so you can listen on any ancestor.

lime-bundle:add-to-cart

Fired on CTA click. Cancelable: event.preventDefault() suppresses the default checkout redirect.

event.detail: {
  lines: CartLineInput[];  // merchandiseId + quantity + attributes
}

Every line's attributes[] array includes { key: "_lime_bundle_gid", value: bundleId }. Preserve it on the way to Shopify cart mutation or purchase attribution breaks.

lime-bundle:loaded

Fired once the bundle(s) have been fetched and parsed.

event.detail: {
  bundleCount: number;
  bundleTypes: Array<"fixed" | "volume" | "mix_match">;
}

lime-bundle:error

Fired if fetch or parse fails.

event.detail: { message: string; code: string }  // e.g. "LOAD_ERROR"

The widget renders its own inline fallback; listen for this event if you want to hide the parent or report to your own telemetry.

What the widget handles for you

• Merchant styling. Every --lb-* CSS variable the merchant configured in the admin is applied inside the shadow root on render.
• Custom CSS. shop.metafields["$app"].custom_css is auto-fetched, sanitized, and injected.
• Countdown timer. When a bundle has endsAt, the widget ticks live and hides on expiry.
• Variant dropdowns. Products with multiple eligible variants render a <select>; switching live-updates the row price and bundle total.
• Mix-match picker modal. Full modal with search, quantity stepper, progress bar, focus trap, and keyboard navigation.
• Out-of-stock handling. Sold-out products render greyed out with the CTA locked; a bundle that can't be completed doesn't render.
• A/B testing. Reads the merchant's A/B config, buckets the visitor via a first-party cookie, applies Variant B overrides.
• Analytics. Impression and add-to-cart events fire regardless of whether you override the cart.

Styling

Override any CSS custom property on the host element:

<lime-bundle
  shop-domain="..."
  style="--lb-primary-color: #e91e63; --lb-radius: 16px;"
></lime-bundle>

Full variable reference: css-variables.md.

Non-React framework snippets

Astro:

<lime-bundle shop-domain="..." storefront-token={import.meta.env.PUBLIC_LIME_BUNDLES_TOKEN} />
<script>
  import "@lime-bundles/widget";
</script>

Vue 3. Configure app.config.compilerOptions.isCustomElement = (tag) => tag === "lime-bundle" to silence the unknown-element warning.

Svelte. No configuration needed; use on:lime-bundle:add-to-cart={handler}.

Bundle size

IIFE build, gzipped: <30 KB. No runtime framework dependency.

Version policy

All three packages (core, react, widget) bump majors together. The v2.0.0 release closes full rendering parity with the admin preview.

License

MIT. See LICENSE.

Support

Merchant support and bug reports: email via the Lime Bundles listing on the Shopify App Store.