The Homebox Platform: Widgets

Our widgets can get you going with the Homebox Open Platform very 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.

Widget Options

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

partnerIDn/aYour unique partner ID, i.e 10001
serviceTypeenergyenergy, broadband, homeInsuranceThe 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.usageEstimatesPresetmediumhigh, medium, lowPre-define user usage estimates based on OFGEM averages
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',
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.
steps (object) Settings for the initial steps of the widget
steps.energyIntroHomebox 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.