Storefront Widgets

Storefront Display#

Enabling App Blocks on Your Theme#

For bundles to appear on your storefront, you need to add the xBundle app blocks to your Shopify theme. This is the most important setup step.

What are app blocks?

App blocks are widgets that xBundle adds to your storefront. They display bundle discount offers, Mix & Match product cards, Multipack offers and Frequently Bought Together recommendations to your customers. Without them, bundles will exist in xBundle but won’t be visible on your store.

How to enable app blocks:

Back in xBundle, the badge refreshes on its own for about a minute and a half after you click Install or Uninstall. If it hasn’t updated, reload the Settings page.

Adding a block by hand: you can also add any block directly in the theme editor. Open your live theme (Online Store → Themes → Customize), pick Products → Default product from the template dropdown, click Add block and choose the xBundle block from the Apps group. The blocks appear in the theme editor under these names:

The Bundle Discount & Mix & Match Widgets#

Fixed and Mix & Match bundles are shown by two related blocks:

• Bundle discount widget (Fixed & Mix & Match) (theme editor name: Discount Bundle): displays the bundle’s discount cards for both Fixed and Mix & Match bundles.
• Mix & Match bundle widget (theme editor name: Bundle Product Card): the product-card widget that lets customers pick the products that go into a Mix & Match bundle.

How it works:

• When you create a Fixed or Mix & Match bundle, xBundle creates a new bundle product in your Shopify catalogue, named after your bundle. The widgets render on that bundle product’s page, not on the individual member products’ pages.
• Link to the bundle product (from a collection, your navigation, or a campaign) to send shoppers to the offer.
• Customers add the bundle with your theme’s own Add to cart (or Buy it now) button on that page. The bundle’s discount is applied automatically; no discount code is needed.

What customers see: the discount cards

Each discount you configured on the bundle appears as a card showing:

• The discount’s name, with a “Click to see details” prompt
• The discount value, for example “20%”, “$10 off”, “Free Gift”, “50% off Gift” or “Free Shipping”
• Optionally, a stock line such as “Only 5 left in stock”
• A countdown timer when the discount has an end date
• A Select Gift Products button on Buy X Get Y discounts, which opens a popover where the shopper picks their gift(s)

Clicking a card opens a Conditions popover listing the discount’s requirements (quantity, cart value and stock conditions). Cards are hidden before their start date and after their end date.

What customers see: the Mix & Match product cards

On a Mix & Match bundle page, the Mix & Match bundle widget lists the products the shopper can choose from. Each card shows the product image, title and price, its stock status (for example “3 left”, “12 available” or “Out of stock”), a variant dropdown when the product has several variants, a quantity picker (1 to 10) and an Add button that changes to Added once selected. A summary shows the running total and how many items are selected. Your theme’s Add to cart button stays disabled until at least one product has been added, and then adds only the selected products to the cart.

Customization:

Each xBundle block ships with its own settings in the Shopify theme editor. Select the block there to adjust the following, in addition to the block’s position on the page. The widgets otherwise inherit your theme’s fonts and styles.

Discount Bundle block:

• Design Settings: Card Color, Text Color, Card Size (Small (240px), Medium (340px) or Large (400px))
• Timer Settings: Show Timer
• Condition Visibility: Show Quantity Condition, Show Cart Value Condition, Show Inventory Condition
• Text Customization: Click to see details text, Show inventory in card, Inventory message (default Only {count} left in stock; use {count} as the placeholder for the quantity, other numbers in the message are fine), Conditions Header, No Conditions Text, Select gifts button and popover title
• Validation Text Templates: the wording of each condition shown in the Conditions popover (Quantity Min Only, Quantity Min & Max, Cart Value Min Only, Inventory Min & Max, their “(Negated)” variants, and so on), using {min} and {max} as placeholders

Unticking any “Show …” checkbox turns that element off.

Bundle Product Card block:

• Text: Currency symbol, No items selected text, Item selected (singular), Items selected (plural), Add button text, Added button text
• Colours: Add button background, Add button text color, Selected button background, Add button hover background, Card background, Card border color, Selected card background, Image background, Title color, Product title color, Price color, Summary background, Summary border color, Card hover background, Items count text color, Total price text color, No image text color
• Font sizes: Product title font size and Price font size (10 to 24 px)

The FBT and Multipack Widgets#

xBundle includes dedicated widgets for Frequently Bought Together recommendations and Multipack volume offers. Unlike Fixed and Mix & Match, these bundle types do not create a new product: the widget appears on the page of the product you built the bundle on.

Frequently Bought Together (FBT) widget (theme editor name: FBT Bundle)

The widget appears on the main product’s page. What customers see:

• A “Frequently Bought Together” heading and subtitle (both editable)
• The main product alongside the recommended products, each with an image, title, price, stock line (“5 in stock” or “Sold out”), a variant dropdown when needed and a quantity picker
• A checkbox on every item to include or exclude it; sold-out items are unticked and disabled
• A running Total: with the original price struck through and the saving (for example “Summer deal - Save $12.00 (20% OFF)”), or “Discount conditions not met” when the discount’s conditions aren’t satisfied
• A countdown timer when the discount has an end date
• A Buy this bundle now button that adds all ticked items to the cart

Which products are recommended is decided when you set up the bundle, and the order of precedence is fixed; it is not a setting. The widget shows, in this order: the products you added under the Manual tab, then Automatic, then Random (a product added in a higher tab is automatically removed from the lower ones), followed by your store-wide Global recommendations (Settings → All → Global recommendations, up to 5 products), and finally any gift products from a Buy X Get Y discount. The widget displays up to 7 recommended products (not counting gifts), so Global recommendations appear only when your Manual, Automatic and Random products leave room.

The FBT Bundle block can also be placed on the cart template in the theme editor, but it has nothing to show there; recommendations belong to the product page being viewed.

FBT Bundle settings in the theme editor:

• Content: Bundle Title (default “Frequently Bought Together”), Bundle Subtitle (default “Customers who bought this item also bought”)
• Timer Settings: Show countdown timer, Timer format (Days, Hours, Minutes, Seconds / Hours, Minutes, Seconds / Minutes, Seconds), BXGY Savings Text, Timer position (Under title / Between total and button), Timer style (Segments, Compact, Text, Badge or Minimal), Timer background color, Timer text color
• Discount Rules: Show discount rules, Rules display style (Tooltip (hover/click) / Inline (always visible) / Badge with icon), Rules background, Rules text color
• Quantity Rule Texts, Cart Value Rule Texts, Inventory Rule Texts: the wording of each condition, using {min} and {max} as placeholders
• Layout: Max width (px) caps the widget’s width and centres it (default 1100; set it to 0 to fill your theme’s container)

Multipack bundle widget (theme editor name: Multipack)

The widget appears on the page of the product the multipack was created for. What customers see:

• One card per pack, sorted by quantity, showing the pack name (for example “2-Pack”, or “Buy 2 items” if you didn’t name it) and the saving (“Save 10%”, “Save $5.00”, “Free Shipping” or “Get 1 gift free”)
• The pack total: the discounted price for the whole pack, with the full pack price struck through. Prices are pack totals, not per-item prices.
• A Most Popular! badge. If you ticked Mark as most popular on one of a pack’s discounts when creating the bundle, that pack gets the badge and is pre-selected. If you didn’t mark one, the widget badges the second pack automatically whenever there are three or more packs, and pre-selects the first pack.
• Optionally, a stock message (“Only 5 left in stock” or “Out of stock”) for products that track inventory and don’t continue selling when out of stock
• A countdown timer on packs whose discount has an end date
• Gift products to choose from on Buy X Get Y packs and, when a pack allows several variants, a per-variant quantity picker to split the pack across variants

Selecting a pack sets the quantity, and your theme’s Add to cart button then adds that pack with its discount applied automatically. The widget hides your theme’s own variant picker on multipack product pages, since variants are chosen inside the pack card. The shopper’s chosen pack is remembered for the rest of their browsing session.

Multipack settings in the theme editor:

• Design: Accent Color, Card Background, Card Width (px) (200 to 600, default 320)
• Display Settings: Show Popular Badges, Card Layout (Vertical (Stacked) / Horizontal (Side by Side))
• Timer & Rules: Show Countdown Timer, Timer Style (Default Timer / Badge + Countdown / Simple Block (Ends in HH:MM:SS) / Inline Red Block (Ends in HH:MM:SS)), Timer Position (Badge Style) (Bottom of Card / Under Price / Under Pack Name), Rules to Show (None, Cart Rules Only, Inventory Rules Only, Quantity Rules Only, Cart & Inventory, Cart & Quantity, Inventory & Quantity or All Rules), AND Conditions Text, OR Conditions Text
• Rule Texts: the wording of each condition, using {min} and {max} as placeholders
• Inventory Display Messages: In Stock Message (default Only {count} left in stock; use {count} for the quantity), Out of Stock Message (default “Out of stock”)

Enabling these widgets:

Both widgets need to be enabled separately in Settings → Widgets bundles. Each has its own app block that you add through the Shopify theme editor.

The “Disable Dummy Bundle Cart” App Embed#

Mix & Match bundles use a placeholder (“dummy”) bundle product to host the bundle widget on its product page. This theme app embed (installed/uninstalled, not a settings toggle) disables the Add to Cart buttons on those placeholder products wherever they appear on your Home, Collection and Search pages, so shoppers build the real bundle on the product page instead of adding the empty placeholder. On the cart page it also removes any placeholder product that has slipped into the cart.

How to install/uninstall it: