@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. | | 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. |

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

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

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. Honours widgetConfig.outOfStockBehavior (hide vs show_greyed_out); hides the widget when the bundle is unfulfillable.
• 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.

Support

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