The Homebox Platform: Widgets

Our widgets get you going with the Homebox Platform rapidly. They give you a way to provide the highly valuable features of finding, comparing & switching to better household services for your users. And beyond that your users can manage their household services more easily and feel confident that they're always on good deals.


We currently provide a single highly-configurable widget which allows simple comparison & switching of various household services within your website or application.

See examples here and here.

In the head section of your HTML source add the following code snippet to load our JavaScript:In the body section add the following tag, which the widget will be rendered on:

The Homebox widget will render wherever you place this div tag.


When you're ready to go live, load the widget from the live server. All data submitted in live mode will be instantly processed.



Widget Options

Properties of the options object can be set to the following:

targethomeboxComparisonA custom HTML ID to render the widget to, useful when rendering multiple instances of the widget on a single page.
partnerIDn/aYour unique partner ID, passed as a string e.g 10001
serviceTypeenergyenergy, broadbandThe type of home service
comparisonTypefullfull, simple, quickfull = step-by-step comparison first

simple = table of deals shown with minimum questions

quick = table of deals shown first / links to hub.homebox to complete journey
comparisonFilters (object) Default preset settings for filters & options for filter display
comparisonFilters.start0(number 0 - 200)Determines how many results to show in the comparison table by default
comparisonFilters.end10(number 1 - 50)Determines how many results to show in the comparison table by default
comparisonFilters.greenOnlyfalsetrue, falseWhether to only show green deals by default
comparisonFilters.greenOnlyDisplaytruetrue, falseWhether to show the green only filter at all
comparisonFilters.fuelTypeDisplayfalsetrue, falseWhether to show the fuel type (dual, electricity only, gas only) filter
comparisonFilters.paymentMethodDisplayfalsetrue, falseWhether to show the payment method (monthly direct debit, prepayment etc.) filter
comparisonFilters.contractTypeDisplayfalsetrue, falseWhether to show the contract type filter (fixed & variable prices, fixed only, variable only)
comparisonFilters.minimumBroadbandSpeed00,30,60Pre-define minimum broadband speed filter
comparisonFilters.minServiceRating0.40, 0.2, 0.4, 0.6, 0.8, 1Minimum service rating of suppliers to show by default. Scale is displayed to the end user as a 5 star scale. 0.2 = 1 star, 0.4 = 2 stars etc..
comparisonFilters.suppliers(all)Array of supplier IDsUse our API to retreive supplier IDs
comparisonFilters.hideAllfalsetrue, falseHide the filter system entirely.
comparisonTable (object) Default settings for the comparison table
comparisonTable.showLoadMoretruetrue, falseShow the 'load more' option below the comparison table. Note: not recommended to disable.
comparisonTable.showFAQstruetrue, falseShow the FAQ section below the comparison table. We recommend keeping this enabled.
comparisonTable.showHeadertruetrue, falseShow the step-by-step information above the comparison table
comparisonTable.showCallouttruetrue, falseShow the highlighted callout above the comparison table
user (object) Pre-fill user details
user params
    firstName: 'Test',
    lastName: 'Smith',
    email: '[email protected]',
    telephone: '07900000000',
    address: {
      addressLine1: 'Flat 7',
      addressLine2: '12 Long Lane',
      locality: 'London',
      region: 'Greater London',
      postcode: 'E11AA',
      mpan: '12345',
      mprn: '12345',
      msnElectricity: '12345',
      msnGas: '12345'
Pre-fill user details
settings (object) Widget global settings
settings.showSwitchConfirmationtruetrue, falseShow a screen after clicking 'switch now' which confirms the details of the deal before the user is taken off-site (broadband only).
settings.amplitudeId(default ID)(custom ID)Analytics ID.
settings.runExperimentsfalsetrue / falseOpt-it to beta experiments.
settings.switchFormMpxnsfalsetrue / falseShow inputs for collecting energy reference numbers on the switch form (MPAN & MPRN numbers).
settings.switchFormMsnsfalsetrue / falseEnable collecting energy meter serial numbers on the switch form.
settings.externalRefAn external reference, typically the user ID of a customer on your systems. This reference will be visible in reports and via our API, for linking each space and switch back to your users.
service (object) Pre-populated information about the current service the user has.
service params
      supplierId: '59e11238e89d353f2732724b',
      supplierName: 'British Gas',
      endDate: '2023-03-25',
      productDetails: {
        paymentMethod: 'mdd',
        meterTypeElectricity: 'standard',
        meterTypeGas: 'standard',
        category: 'electricityOnly',
        productId: '5dceec8254dfec77a14f22fc',
        productName: 'Temporary July 20',
See our developer documentation for details of the accepted properties. For enum types hover over the '+1'.
service.usageEstimatesPresetmediumhigh, medium, lowPre-define user usage estimates based on OFGEM averages
service.usageEstimatesKnownnulltrue, falseDefine whether the user knows their usage estimates or not. If set to false, the usage estimate presets will be displayed by default.
    usageType: 'gas',
    timeframe: 'year',
    unit: 'kwh',
    amount: '12000',
    usageType: 'electricity',
    timeframe: 'year',
    unit: 'kwh',
    amount: '2000',
Pass through an array containing two objects which describe energy usage in `kwh` or `cost`. Timeframe can be set to `month`, `quarter` or `year`.
steps (object) Settings for the initial steps of the widget
steps.introTextHomebox controller introCustom HTMLUser-set intro text and HTML.


Special function to dynamically update comparison filters from outside of the widget app.


    suppliers: [


Special function to dynamically update user details.


    address: { postcode: 'BR22AA' },
    firstName: 'Test 2'

Data Management

While a user is interacting with our widgets, we only ever use anonymised non-personal data for analytics purposes, this includes things like which buttons a user clicks on and how long they spend looking through comparison results. Any personal data (i.e the user's name or address) is by default only stored on the user's computer (in localStorage) and is not sent to us or any third-party analytics apps.

After a user signs up, or submits data to the Homebox platform (i.e when submitting a switch directly from within the widget) - they will agree to Homebox's T&Cs which include our data processing terms.


Analytics (Amplitude). For details, please visit Amplitude. These cookies are used to collect information about how users use our widget. We use the information to analyse behaviour and to help us improve our services. The cookies collect information in an anonymous form, including the number of visitors to the website and blog, where visitors have come to the website from and the pages they visited.