The HubBox Tag is a JavaScript-based solution for adding HubBox pickup point selection directly into your website's checkout frontend. It is designed as a light-weight and low-code integration for platforms where deep backend modifications are difficult or restricted.
For highly customized checkout experiences or deeper backend integration needs, consider the HubBox Software Development Kit instead.
A JavaScript snippet (the "Tag") is added to your checkout page. This script defines a configuration object and loads the main HubBox payload from the HubBox CDN. Together, they:
| Requirement | Details |
|---|---|
| HubBox Tag script | The JavaScript snippet prepared by your HubBox Integrations Manager, tailored for your checkout page |
| Checkout page access | Ability to add JavaScript to your checkout page via theme files, a script manager, or a tag manager |
| CSS selectors | Knowledge of the CSS selectors for your checkout's shipping address form fields |
You can access the Tag script via Console by going to "Setup" and then "Tag Management" in the menu.
HubBox will provide a single line you add to your checkout page. It points to your HubBox-hosted Tag file on the CDN:
<script src='tags.hub-box.com/production/your-config-id/hubbox-tag.js' defer async></script>
HubBox hosts and maintains this file. You do not need to paste or manage the script contents directly — only the <script src="..."> reference needs to be added to your site.
For more informatin on how the Tag script is put together, please see below the four key parts working together in the browser.
1. Initialization SnippetThe main piece of code you add to your site. It defines a global window.HUBBOX object that the payload script reads on load.
Nested within window.HUBBOX.payload, this JSON object contains all the settings, selectors, and customisations that control the Tag's behaviour on your specific site. This is the primary object you or the HubBox team will modify.
The initialization snippet dynamically loads the core HubBox Tag functionality from a HubBox CDN URL (e.g., cdn.hub-box.com/tag-payload/x.y.z/tag-payload.iife.js). This payload reads the config object and executes the necessary actions.
Custom CSS rules, injected alongside the main script or defined within it, are used to style the HubBox UI elements to match your brand.
// 1. Initialization Snippet
window.HUBBOX = {
payload: {
// 2. Config Object
config: {
configId: "your_unique_config_id",
environment: "production",
mode: "live",
language: "en",
launchExperience: { /* ... */ },
addressFields: { /* ... */ },
callbacks: { /* ... */ },
translations: { /* ... */ }
}
}
};
// 3. Optional: Inline CSS
var styles = `
:root { --button-color: #FF0000; }
hubbox-local-pickup-toggles::part(title) { font-weight: bold; }
`;
var styleSheet = document.createElement("style");
styleSheet.innerText = styles;
document.head.appendChild(styleSheet);
// 4. Load Payload Script from CDN
setTimeout(function () {
var script = document.createElement("script");
script.type = "text/javascript";
script.async = true;
script.src = "cdn.hub-box.com/tag-payload/6.2.1/tag-payload.iife.js";
document.getElementsByTagName("head")[0].appendChild(script);
});
The HubBox Integrations team analyses your checkout page structure and prepares the initial Tag script, focusing on the essential configuration: configId, launchExperience.injection, and addressFields.selectors.
When your Tag script is ready, you can access it via Console by going to "Setup" and then "Tag Management" in the menu.
Add the prepared script to your checkout page using the method appropriate for your platform:
Load the script in the footer where possible. Ensure it fires on the checkout page where shipping options are presented.
Thoroughly test using the Tag's built-in test mode. See the Testing the Tag Implementation section below.
The HubBox team typically assists with initial styling. Further customisations can be made by editing the CSS or the config object. See the #customising-appearance-styling and #advanced-configuration sections below.
Once testing is complete, switch the Tag to live mode. See the Going Live section below.
The config object within window.HUBBOX.payload controls most of the Tag's behaviour. The table below describes the common top-level properties.
| Property | Type | Description |
|---|---|---|
configId |
String | Identifies your HubBox configuration. Determines which networks, base styles, and widget settings are loaded. Provided by HubBox. |
environment |
String | "sandbox" for testing or "production" for live. |
mode |
String | "test" requires ?hubboxPayloadTest=true in the URL to show HubBox. "live" shows HubBox to all users. |
language |
String | Sets the primary UI language (e.g., "en", "en-GB", "fr", "de"). |
logLevel |
String | Console logging verbosity: "DEBUG", "INFO", "WARN", "ERROR", "OFF". Use "DEBUG" during setup. |
launchExperience |
Object | Defines how the Home/Pickup choice is presented. |
addressFields |
Object | Maps HubBox address data to your checkout form fields. |
carrierSpecificDataInjection |
Object | Configures how carrier-specific codes (e.g., DPD S2S, UPS .D2R.) are written to address fields. |
shippingMethods |
Object | Configures shipping rate filtering. |
callbacks |
Object | Executes custom JavaScript at specific points in the Tag lifecycle. |
translations |
Object | Overrides default UI text strings. |
These config sections are fundamental to making the Tag work correctly on your checkout page. HubBox configures these initially based on your site analysis.
Defines how the initial Home Delivery / Local Pickup choice is presented to the customer.
config: {
launchExperience: {
design: 'toggles', // Visual style: 'toggles', 'multi-button', 'stacked', 'switch', 'tab'
injection: {
reference: '#checkout-shipping-options', // CSS selector of an existing element on your page
positioning: 'beforebegin', // 'beforebegin' | 'afterbegin' | 'beforeend' | 'afterend'
},
swapComponents: false, // Set to true to swap the visual order of Home vs Pickup options
persist: true, // Prevents the Tag from disappearing when a customer edits their address mid-checkout
},
}
design controls the visual appearance of the choice (e.g., radio-style toggles, larger buttons).
injection tells the Tag where to physically insert the Home/Pickup choice elements into your checkout page DOM:
reference — a CSS selector targeting a stable existing element on your checkout page.positioning — where to insert relative to the reference element, using standard insertAdjacentHTML positioning values.persist — set to true to prevent the Tag from disappearing when a customer edits their shipping address mid-checkout. Recommended for most implementations.
Maps the selected pickup point's address details to your checkout form's input fields.
config: {
addressFields: {
selectors: {
// Map HubBox address parts to CSS selectors for your form fields
company: "#shipping-company-field",
address1: "#shipping-address1-field",
address2: "#shipping-address2-field",
city: "input[name='shipping_city']",
county: "#shipping-state-selector",
postcode: "#shipping-postcode-input",
country: "#shipping-country-select"
},
interactionPreventionAction: "lock", // 'lock' | 'hide' | 'hide parent' | 'hide .{selector}'
// Can combine with | e.g. "lock | hide .form-group"
},
}
selectors — each key must contain the correct CSS selector for the corresponding input or select field in your checkout form. HubBox uses these selectors to populate the form when a pickup point is chosen.
interactionPreventionAction — defines what happens to the mapped address fields after a pickup point is selected, preventing the customer from manually overriding the pickup address. "lock" (disabling the fields) is the most common setting.
Handles how carrier-specific codes required for manifesting (e.g., DPD S2S..., DHL DHL..., UPS .D2R...) are written into address fields.
config: {
carrierSpecificDataInjection: {
dpd: {
action: 'set',
destination: 'address2' // Which addressFields.selectors key receives the code
},
ups: {
action: 'set',
destination: 'address2'
}
// Add entries for other carriers as needed
},
}
HubBox configures this based on the networks used and your checkout form structure, ensuring manifesting codes are placed correctly.
For advanced control, you can override the default injection point for the map widget modal or the post-selection confirmation block.
config: {
widget: {
injection: {
// reference: 'body',
// positioning: 'beforeend'
}
},
pickupConfirmation: {
design: 'modern', // 'modern' | 'blank' | 'legacy'
injection: {
// reference: '#shipping-summary',
// positioning: 'afterbegin'
}
},
}
Provides custom mapping of county names to county codes. This is primarily used for UK counties where the checkout form requires a county code rather than a full county name.
config: {
stateLookups: {
"Greater London": "LND",
"West Yorkshire": "WYK",
"Greater Manchester": "GTM",
// ... all 86 UK counties must be mapped when using this option
},
}
When using stateLookups, all 86 UK counties must be mapped. Partial mappings may result in unmapped counties being passed as-is. Matching is case-insensitive. Values can be strings or numbers.
Provides platform-specific configuration for supported checkout frameworks.
config: {
framework: {
// BigCommerce-specific options
bigCommerce: {
trackingPixel: false,
customerId: {{customerId}} // Required if trackingPixel is enabled
},
// Magento-specific options
magento: {
selectors: {
addNewAddress: "[data-action='add-new-address']",
shippingAddressItems: ".shipping-address-items",
}
}
},
}
Consult your HubBox Integrations Manager for the correct framework configuration for your platform.
The most common method is to include a CSS block within your Tag script or load a separate CSS file alongside it.
var styles = `
:root {
--hb-primary-color: #0056A0;
--hb-button-color: #0056A0;
--hb-button-text-color: #FFFFFF;
--hb-border-radius: 4px;
--hb-font-family: inherit;
}
hubbox-local-pickup-toggles::part(title) {
font-weight: bold;
color: var(--hb-primary-color);
}
hubbox-modal::part(header) {
background-color: var(--hb-primary-color);
color: white;
}
`;
var styleSheet = document.createElement("style");
styleSheet.innerText = styles;
document.head.appendChild(styleSheet);
HubBox UI elements are built using Web Components. To style elements inside these components (which are encapsulated in a shadow DOM), use the ::part() pseudo-element. Target the component tag name followed by ::part(part-name).
Part names are documented in the HubBox Components documentation or can be found by inspecting the element's HTML in browser developer tools (look for the part="..." attribute).
/* Style the title text within the local pickup toggle */
hubbox-local-pickup-toggles::part(title) { color: blue; }
/* Change the icon in a multi-button component */
hubbox-local-pickup-multi-button::part(icon) {
content: url(cdn.hub-box.com/assets/icons/store.svg);
}
/* Change icon colour using CSS filter */
hubbox-local-pickup-toggles::part(icon) {
filter: invert(100%) sepia(0%) saturate(2%) hue-rotate(107deg) brightness(111%) contrast(101%);
}
Use standard CSS Grid or Flexbox targeting the component tags or their ::part(container) to adjust layout (side-by-side vs. stacked, width).
For the full list of available part names, CSS variables, and styling examples, refer to the HubBox Components documentation or the style examples provided by your HubBox Integrations Manager.
Use config.language to set the base locale (e.g., "en-GB", "fr-FR", "de-DE").
Use the config.translations object to override specific text strings. Provide translations under the same language code set in config.language.
config: {
language: "en-GB",
translations: {
"en-GB": {
localPickup: {
localPickup: "Collect from Store",
select: {
selectedState: {
active: "(Chosen)",
inactive: "Choose this",
neutral: "Choose this"
}
}
},
homeDelivery: {
homeDelivery: "Ship to my Address",
},
pickupConfirmation: {
thankYou: "Thanks for choosing Click & Collect!",
orderWillBeSent: "Your order is heading to your chosen {network} point.",
},
modal: {
headerLine1: "Find your nearest collection point",
}
}
// Add other language blocks as needed, e.g. "fr-FR": { ... }
},
}
Refer to the /docs/components-installation for the available component keys (e.g., localPickup, homeDelivery) and text keys within each component.
Callbacks allow you to execute custom JavaScript at specific points in the Tag's lifecycle or in response to user actions. They are defined within config.callbacks.
| Callback | When It Fires |
|---|---|
onCheckoutPageLoaded |
When the Tag first initialises on the checkout page |
onWebComponentsCreated |
After the HubBox UI Web Components have been created and added to the page |
onLocalPickupSelected |
After the user selects "Local Pickup", before the map widget opens |
onHomeDeliverySelected |
After the user selects "Home Delivery" |
onAddressFieldsPopulated |
After HubBox has populated the address fields with a pickup point's details |
utils)The utils object passed to some callbacks provides DOM helpers:
utils.$(selector) — equivalent to document.querySelector.utils.$(selector).click() — simulate a click.utils.$(selector).general.show() / .hide() — show or hide elements.utils.$(selector).input.checkbox.check() / .uncheck() — interact with checkboxes.config: {
callbacks: {
onLocalPickupSelected: (utils) => new Promise((resolve) => {
console.log("Local Pickup Selected!");
// utils.$('.home-delivery-message').general.hide();
resolve();
}),
onHomeDeliverySelected: (utils) => new Promise((resolve) => {
console.log("Home Delivery Selected!");
// utils.$('.home-delivery-message').general.show();
resolve();
}),
onWebComponentsCreated: ({ localPickup, homeDelivery }) => new Promise((resolve) => {
// Set translations (must match config.language code)
localPickup.translations = { "en-GB": { localPickup: "Collect Here" } };
homeDelivery.translations = { "en-GB": { homeDelivery: "Deliver To Me" } };
// Set price info items displayed beneath each toggle
localPickup.priceInfoItems = ['Usually Free!', 'Ready in 24h'];
homeDelivery.priceInfoItems = ['Standard: £3.99'];
// Set additional info items on the local pickup component
localPickup.additionalInfoItems = [
{ text: "Available at 1,000+ locations" },
{ text: "No signature required" },
{ text: "Hold for up to 7 days" }
];
resolve();
}),
}
}
priceInfoItems — an array of strings displayed beneath the toggle label for each delivery option. Useful for communicating pricing or delivery time at a glance.
additionalInfoItems — an array of objects with a text property, displayed as supplementary information beneath the Local Pickup toggle.
Use this feature to hide the HubBox UI entirely when the cart contains ineligible items (e.g., oversized, hazardous, or high-value goods). Implement callbacks.getShouldBailOut within your config. The function must return a Promise that resolves to true to hide HubBox, or false to show it.
For eligibility strategy guidance, refer to the /docs/product-eligibility. For platform-specific cart data access examples, refer to the /docs/woocommerce and /docs/bigcommerce guides.
config: {
callbacks: {
getShouldBailOut: () => new Promise(resolve => {
// 1. Fetch or access cart data
// 2. Check items against your eligibility rules (SKU, category, dimensions, value)
const shouldBailout = false; // Replace with your actual check result
// 3. Resolve the promise
resolve(shouldBailout);
}),
}
}
Use this feature to show or hide specific shipping rate options based on whether Home Delivery or Local Pickup is selected. For strategy guidance, refer to the /docs/shipping-rate-filtering.
config: {
shippingMethods: {
wrapper: '#shipping_method', // CSS selector for the container holding all shipping rates
interactionPreventionAction: 'hide li', // How to disable rates when pickup is selected
excludeOnLocalPickup: [
{
selectors: [
'text-fragment: Royal Mail',
'text-fragment: Evri',
],
},
],
excludeOnHomeDelivery: [
{
selectors: [
'text-fragment: Pickup',
],
},
],
},
}
Rule object properties:
selectors — array of strings to identify shipping methods to hide. Use text-fragment: Your Rate Name to target by visible text.networks (optional) — array of network keys (e.g., ["ups", "dpd"]) to apply the rule only when specific networks are active.mode (optional) — "first" (default) hides only the first matching element; "all" hides all matching elements.Controls on which pages the Tag actively executes its core logic. The Tag checks window.location.href against the provided regex patterns.
config: {
urlRegex: {
checkout: "^.*(checkout|cart).*$",
confirmation: "^.*(order-confirmation|success).*$"
},
}
Ensure patterns accurately match your checkout page URL structure. Incorrect patterns will prevent the Tag from loading where needed.
Delays Tag initialisation by the specified number of milliseconds. Use this when shipping rates or other checkout elements take time to load after the page is ready, which can otherwise cause the Tag to initialise before its injection target exists.
config: {
launchDelay: 1000, // Delay in milliseconds (e.g., 1000 = 1 second)
}
Use standard JavaScript conditional logic when defining config values to apply different configurations based on the current domain. This is useful for businesses managing multiple brands or regional sites from a shared codebase.
config: {
configId: (
window.location.hostname === "brand-a.com"
? "brandA_prod_config"
: "brandB_prod_config"
),
language: (
window.location.hostname.endsWith(".fr")
? "fr-FR"
: "en-GB"
),
}
Use the onWebComponentsCreated callback to access the modalComponent instance and set noHeader to true.
config: {
callbacks: {
onWebComponentsCreated: ({ modalComponent }) =>
new Promise((resolve) => {
if (modalComponent) {
modalComponent.noHeader = true;
}
resolve();
}),
}
}
To prevent the modal from overflowing off-screen, particularly on mobile, set a max-height on the modal panel part.
hubbox-modal::part(panel) {
max-height: 95vh;
overflow-y: auto;
}
If the modal appears underneath other checkout elements due to z-index stacking issues, you can inject the modal directly into <body>. Use this cautiously — it changes the DOM structure. Consult HubBox support before using this approach.
config: {
modalInjection: {
reference: "body",
positioning: "append"
},
}
Controls how the Tag interacts with your checkout's "Shipping address is the same as billing address" checkbox. When a pickup point is selected, the shipping address differs from the billing address, so this checkbox typically needs to be automatically unchecked.
config: {
shippingAsBilling: {
checkbox: "#shipping-same-as-billing-checkbox",
interactionPreventionAction: "hide", // 'hide' | 'lock' | 'hide parent'
invert: false // Set to true ONLY if your checkbox label means
// "Billing is DIFFERENT from Shipping" (rare)
},
}
Set invert: false if your checkbox label means "Shipping address is the SAME as billing". Set invert: true only if the label means "Billing address is DIFFERENT from shipping".
Prevents the customer from accidentally saving a pickup point address to their personal address book when the "Save this address for future use" checkbox is present.
config: {
saveAddress: {
checkbox: '#save-shipping-address-checkbox-id',
interactionPreventionAction: 'hide parent' // Hide the checkbox and its immediate container
},
}
Hides or locks miscellaneous checkout elements when Local Pickup is active. Accepts an array of rule objects.
Use cases include hiding delivery instruction fields, disabling form sections irrelevant to pickup, or hiding home-delivery-only promotional banners.
config: {
otherElements: [
{
selector: '#delivery-instructions-neighbour',
interactionPreventionAction: 'hide'
},
{
selector: 'fieldset.special-delivery-options',
interactionPreventionAction: 'hide'
},
{
selector: '#gift-wrap-home-option',
interactionPreventionAction: 'lock'
}
],
}
enterAddressManually and addNewAddressThese options handle edge cases where the checkout requires a button click to register that a new address has been populated — common in some Magento and multi-address checkout flows.
config: {
// Triggers a click on the specified element after address fields are populated,
// to signal to the checkout that a new address has been entered
enterAddressManually: {
selector: "button[data-target='new-address-fields']",
},
// Hides or locks the "Add new address" option when Local Pickup is active
addNewAddress: {
selector: "#address-choice-new",
interactionPreventionAction: "hide",
},
}
Consult your HubBox Integrations Manager if you are unsure whether these options are needed for your checkout.
Set mode: "test" in your config object within the Tag script. This prevents the HubBox UI from appearing to live customers.
config: {
mode: "test",
logLevel: "DEBUG", // Recommended during testing
}
When mode is set to "test", HubBox only renders when a test trigger is detected. The following trigger methods are supported, in order of priority:
| Method | How to Use |
|---|---|
| URL query parameter | Append ?hubboxPayloadTest=true to your checkout URL |
| URL hash | Append #hubboxPayloadTest=true to your checkout URL |
| LocalStorage | Run localStorage.setItem("hubboxPayloadTest", "true") in the browser console |
| SessionStorage | Run sessionStorage.setItem("hubboxPayloadTest", "true") in the browser console |
| Cookie | Run document.cookie = "hubboxPayloadTest=true" in the browser console |
| Window variable | Run window.hubboxPayloadTest = true in the browser console |
If your checkout appends session or cart UUIDs to the URL (e.g., checkout?session=abc123), the query parameter approach may not work reliably. In these cases, use LocalStorage, SessionStorage, or the window variable method instead.
Only users with an active trigger will see the HubBox UI.
Work through the following checklist:
logLevel: "DEBUG" to get detailed output.For the full HubBox UAT plan, refer to the HubBox testing documentation.
Ensure all checklist items are passed in test mode or on your staging environment.
Edit the HubBox Tag script and change mode from "test" to "live":
config: {
mode: "live",
}
Save and publish your changes. HubBox pickup options will now be visible to all eligible customers.
config.launchExperience.injection.reference targets an element that exists in the DOM before the Tag runs.config.urlRegex.checkout matches your checkout page URL.cdn.hub-box.com.addressFields or shippingMethods can cause errors or unexpected behaviour. Double-check them against the live DOM using browser developer tools.z-index, appearing over the HubBox modal. Add custom CSS to increase the modal's stacking order:hubbox-modal { z-index: 9999 !important; }
hubbox-modal::part(panel) { max-height: 95vh; overflow-y: auto; }
modalInjection config option (see Advanced Configuration above).config.addressFields.selectors are precise and correct for your current checkout form HTML. Inspect the live DOM using browser developer tools to confirm each selector matches the intended input element.interactionPreventionAction is set to the appropriate value for your checkout layout.