HOMS WooCommerce Bundles

A premium WooCommerce plugin that transforms how customers configure product bundles — replacing clunky dropdowns with a modern, step-by-step visual configurator modal complete with image-based option cards, dynamic validation, and seamless cart integration.

Requirements

Installation

Get the plugin running in under five minutes. No external services or API keys required.

Method 1 — Upload via WordPress Admin

1. 01
   Download the plugin ZIP

   Download wc-bundle-configurator.zip from your purchase receipt or account dashboard.

2. 02
   Navigate to the Upload screen

   In your WordPress admin, go to Plugins → Add New → Upload Plugin.

3. 03
   Upload and activate

   Choose the ZIP file, click Install Now, then Activate Plugin.

4. 04
   Verify the menu appears

   A new Bundles menu item should appear in your WP admin sidebar, just below WooCommerce.

Method 2 — Manual FTP Upload

# Unzip the plugin package
unzip wc-bundle-configurator.zip

# Upload to WordPress plugins directory
cp -r wc-bundle-configurator/ /var/www/html/wp-content/plugins/

# Set correct permissions
chown -R www-data:www-data wp-content/plugins/wc-bundle-configurator/

Then activate via Plugins → Installed Plugins in your WordPress admin.

Uninstalling

Deactivate and delete the plugin from Plugins → Installed Plugins. The uninstall hook automatically removes all database tables and options. This action is irreversible — export your bundle data before uninstalling if you may need it later.

Getting Started

Create your first bundle and see it live on a product page in about 10 minutes.

Creating Your First Bundle

1. 01
   Open the Bundles menu

   Navigate to Bundles → Add New in your WordPress admin sidebar.

2. 02
   Select the WooCommerce product

   Use the product dropdown to link this bundle to a specific WooCommerce product. Each product can have one bundle. Once set, the product cannot be changed.

3. 03
   Choose a pricing mode

   Select Fixed Price to use the product's existing price, or Dynamic Price to calculate the total from individual option prices.

4. 04
   Save the bundle

   Click Save Bundle. You'll be redirected to the bundle edit page where you can add steps.

Adding Steps

After saving the bundle, the Steps section becomes active.

1. 01
   Add a step

   Click + Add Step. A new step form appears, collapsed below existing steps.

2. 02
   Fill in the step title

   Use a descriptive name like "Select Squeez Shade" or "Choose Brush Type". This appears as the tab label in the modal.

3. 03
   Choose selection type

   Set to Single (pick one option) or Multiple (pick many, with configurable min/max).

4. 04
   Save the step

   Click 💾 Save Step. The Options section immediately unlocks below the step settings.

Adding Options to a Step

1. 01
   Click Add Option

   The ＋ Add Option button opens a new blank option row inline.

2. 02
   Fill in the Label

   This is the text shown beneath the option card image (e.g. "Blossom", "Chestnut", "Clear"). Required field.

3. 03
   Set a Value (slug)

   An internal identifier, auto-generated from the label if left blank. Used in cart metadata and order records.

4. 04
   Add an image

   Click the Image button to open the WordPress Media Library. Select a product swatch, shade sample, or illustration. Shown as a card image in the frontend modal.

5. 05
   Save the option

   Click 💾 to save. The option count badge updates. Repeat for all options in this step.

Admin Guide

A complete reference for every field, option, and control in the bundle builder.

Bundle Settings

Step Settings

Option Settings

Conditional Logic

Steps can be locked until a specific prior selection is made. This is useful for bundles where certain options only make sense after another choice.

Reordering Steps and Options

Drag the ⠿ handle on any step row to reorder. The modal will display steps in the new order. Options within a step can also be reordered by drag-and-drop. Changes are saved automatically via AJAX.

Frontend Experience

Understanding how the customer interacts with the bundle configurator on the product page.

The Bundle Panel

On any product page linked to a bundle, a Bundle Options panel appears between the product form and the Add to Cart button. It shows:

• A progress counter (e.g. "0/2 selected")
• One row per step, showing the step name and current selection ("Not selected" initially)
• A pink Select button to open the modal

The Configurator Modal

Clicking Select opens the full-screen configurator modal. The modal consists of:

User Flow

1. 1
   Customer lands on product page → sees "Bundle Options" panel with "0/2 selected"
2. 2
   Clicks Select → modal opens to Step 1
3. 3
   Clicks an image card → for single-select steps, auto-advances to Step 2
4. 4
   Completes all steps → Done button activates
5. 5
   Clicks Done → modal closes, panel updates to show all selections
6. 6
   Clicks Add to Cart → selections validated server-side and stored in the cart item

Validation Behaviour

If a customer clicks Add to Cart before completing all selections:

• The Add to Cart button is visually disabled (opacity 0.46, pointer-events none) until all selections are made
• Clicking a blocked Add to Cart shakes the panel and highlights incomplete step rows in red
• Server-side validation runs as a second layer — even if JS is bypassed, the server blocks invalid submissions

Mobile Experience

On screens ≤520px the modal transforms into a bottom sheet that slides up from the bottom edge. A drag handle indicator appears at the top. The option grid switches to a 2-column layout. All touch targets meet the 44px minimum.

Design Settings

Control every visual aspect of the frontend configurator from a single admin page with a live preview.

Accessing Design Settings

Navigate to Bundles → Design Settings in your WordPress admin. Changes are previewed instantly in the right-hand panel. Click Save Settings to apply globally, or Reset to Defaults to restore the original appearance.

Available Settings

How CSS Variables Work

Settings are stored in the wcbc_design_settings WordPress option. On every frontend page load, they are converted to CSS custom properties injected into <head> after the plugin stylesheet, ensuring they always win the cascade:

<style id="wcbc-design-vars">
:root {
  --wcbc-pink:          #c8527a;
  --wcbc-pink-done:     #e8a0b4;
  --wcbc-card-r:        10px;
  --wcbc-modal-r:       20px;
  --wcbc-font-size:     14px;
  --wcbc-spacing-panel: 16px;
  --wcbc-shadow-card:   0 1px 3px rgba(0,0,0,.06);
  /* ...18 more tokens */
}
</style>

Cart & Checkout

Bundle selections persist through the entire WooCommerce order lifecycle — cart, checkout, emails, and order management.

Cart Display

In the WooCommerce cart and mini-cart, bundle selections appear as meta rows beneath the product name:

Preventing Accidental Merging

Two cart items with the same product but different bundle configurations are never merged. The plugin computes a hash of each configuration — identical hashes increment the quantity, different hashes create separate cart rows.

Order Admin Screen

In the WooCommerce admin order view, each bundle step appears as a human-readable meta row. The raw internal meta keys (_wcbc_selections, _wcbc_bundle_id) are hidden from the admin display to keep the UI clean.

Order Confirmation Emails

Bundle selections automatically appear in all WooCommerce transactional emails — customer order confirmation, admin new order notification, and order completed emails. No additional configuration required.

Server-Side Validation

Before any item is added to the cart, the plugin performs a full server-side validation pass:

• Nonce verification (tamper-proof form submission)
• Min/max selection count per step
• Each submitted value must exist as an active option in the database (prevents injection of arbitrary values)
• Conditional prerequisite check (if Step 2 requires a specific Step 1 value)

Any failure produces a WooCommerce notice and blocks the add-to-cart — the item is never added with incomplete or invalid data.

Troubleshooting

Solutions to the most common issues. If your issue is not listed here, enable WP_DEBUG and check the debug log for the exact error.

// Enable debug logging
define( 'WP_DEBUG',         true  );
define( 'WP_DEBUG_LOG',     true  );
define( 'WP_DEBUG_DISPLAY', false );

// Then check: wp-content/debug.log

Developer Hooks

HOMS WooCommerce Bundles is built for extensibility. Use these WordPress actions and filters to customize or extend behaviour without modifying plugin files.

Actions

add_action( 'wcbc_init', function() {
    // Plugin is fully loaded — safe to interact with it
    error_log( 'HOMS Bundles is ready!' );
} );

add_action( 'wcbc_cart_item_restored',
    function( $key, $item ) {
        // $item contains _wcbc_selections, _wcbc_bundle_id, etc.
        error_log( 'Bundle item restored: ' . $key );
    }, 10, 2
);

Utility Methods

The CartIntegration class exposes static helpers for reading bundle data from cart and order items:

use WCBundleConfigurator\Frontend\Controllers\CartIntegration;

// Get structured selections from a WC cart item
$selections = CartIntegration::get_selections_from_cart_item( $cart_item );
// Returns: [ step_id => [ 'step_title', 'values', 'labels' ] ] or null

// Get structured selections from a WC order line item
$selections = CartIntegration::get_selections_from_order_item( $order_item );

// Get the bundle ID attached to a cart item
$bundle_id = CartIntegration::get_bundle_id_from_cart_item( $cart_item );

// Build a deterministic hash for a configuration (for duplicate detection)
$hash = CartIntegration::build_selection_hash( $bundle_id, $selections );

JavaScript Events

The frontend JS state machine dispatches custom DOM events you can listen to:

// Fire when the customer completes all selections
document.addEventListener( 'wcbc:done', function( e ) {
    const { selections, labels } = e.detail;
    console.log( 'Bundle complete:', selections );
    // selections = { [stepId]: string[] }
    // labels     = { [stepId]: string[] }
} );

// Track individual card selections for analytics
document.addEventListener( 'wcbc:selectionChange', function( e ) {
    const { stepId, values, labels } = e.detail;
    // Push to dataLayer, analytics, etc.
    window.dataLayer?.push({
        event: 'bundle_selection',
        step_id: stepId,
        selected_values: values,
    });
} );