Documentation
Widget integration guide
Embed KarbonKit widgets on any website with a single code snippet. Configure appearance, available technologies, and branding to match your site.
Quick start
There are two ways to embed KarbonKit widgets: a plain iframe (works wherever iframes are allowed, stays the height you set) or a script tag (the same one line for every widget, and it resizes itself to fit).
Option 1 – Iframe
Paste this into any HTML page. Works on WordPress, Squarespace, Wix, and static sites. Replace YOUR_CID with the config ID from your dashboard.
<iframe src="https://widgets.karbonkit.com/widget-embed?type=lct-calculator&cid=YOUR_CID" width="100%" height="900" frameborder="0" style="border: none; border-radius: 8px;" allow="clipboard-write" ></iframe>
Option 2 – Script tag
Works for every widget: the loader reads only your config ID, and the widget type, colours and options all come from the configuration saved against it. It resizes the widget to fit its content and passes on the permissions each widget needs (camera, microphone, fullscreen).
<script src="https://widgets.karbonkit.com/embed.js"></script> <div data-karbonkit data-config-id="YOUR_CONFIG_ID"></div>
The loader looks for elements carrying both data-karbonkit and data-config-id. It also accepts the older <div data-heatpump-widget="YOUR_CONFIG_ID"> snippet, reading its value as the config ID. Other older data- attributes, such as data-widget-type, are not read. For new embeds, copy a fresh snippet from your dashboard.
Note: Get your config ID and a ready-to-use snippet from the . Accounts are free.
Integration reference
Every widget, with the values the dashboard puts in its iframe snippet. With the script tag you need none of these: the snippet is the same for every widget and the widget sizes itself.
| Widget | Iframe type= | Script tag | Iframe height | Auto-resizes | Iframe allow= | Config ID | Options (set in the dashboard) |
|---|---|---|---|---|---|---|---|
| Savings calculator | lct-calculator | data-karbonkit data-config-id | 900px | Script tag: yes. Iframe: only with the listener below | clipboard-write | Required | Brand colour; company name; which technologies to offer (heat pump, solar PV, battery); installer finder after results (on by default); caveat banner (up to 240 characters); enquiry collection (off by default) |
| AR heat pump visualiser | heat-pump-ar | data-karbonkit data-config-id | 500px | Script tag: yes. Iframe: only with the listener below | camera; xr-spatial-tracking; accelerometer; gyroscope; magnetometer; fullscreen | Required | Brand colour; background colour; which heat pump model loads first |
| Sound simulator | sound-simulator | data-karbonkit data-config-id | 700px | Script tag: yes. Iframe: only with the listener below | microphone | Optional – without one, default colours and no company name | Company name (shown as "Provided by …"). The widget keeps its own colours; brand colour only tints the footer link |
| 3D house tour | house-tour (also system-diagram) | data-karbonkit data-config-id | 660px | Script tag: yes. Iframe: only with the listener below | fullscreen | Optional – without one, default colours and no company name | Brand colour; company name |
| Installer finder | installer-finder | data-karbonkit data-config-id | 700px | Script tag: yes. Iframe: only with the listener below | none needed | Optional – without one, default colours and no company name | Brand colour; company name; installer source (the public directory, your own list, or both); your own suggested installers |
| Grant eligibility finder | grant-finder | data-karbonkit data-config-id | 900px | Script tag: yes. Iframe: only with the listener below | none needed | Optional – without one, default colours and no company name | Brand colour; company name; link to the visitor's council (off by default); your own local schemes (off by default) |
| Boiler escape plan | boiler-escape-plan | data-karbonkit data-config-id | 1000px | Script tag: yes. Iframe: only with the listener below | none needed | Optional – without one, default colours and no company name | Company name (shown as "Provided by …"); enquiry collection (off by default). The widget keeps its own colours; brand colour is used on the enquiry form and footer link |
Options live in the dashboard, not the snippet. They are saved against your config ID, so a change takes effect on your live page without editing it. When the iframe src carries a dashboard config ID, other URL parameters are ignored (see legacy URL parameters).
Heights are the dashboard’s defaults. On mobile the calculator and boiler escape plan can run past 1500px once content stacks vertically, so a plain iframe either needs more room or the auto-resize listener.
Copy the allow list exactly. A plain iframe missing a permission loads normally and only fails when the visitor taps the button that needs it (View in your room, the decibel meter, fullscreen). The script tag passes on all of them for you.
Use a config ID even where it is optional. Without one there is nothing to change later from the dashboard, and no enquiry collection or local content.
Platform-specific setup
The iframe and script-tag snippets above work on any platform that allows HTML embeds, but each platform has its own way of accepting them. Here's the exact route for the popular ones.
Gutenberg (block editor): Add a new block, search for "Custom HTML", and paste the iframe snippet. The "Custom HTML" block (not "Code") is the right one – "Code" formats the markup as plain text instead of rendering it.
Classic editor: Switch from the "Visual" tab to the "Text" tab before pasting. Pasting into "Visual" will escape the HTML and the iframe won't render.
WordPress.com hosted: Iframes are stripped on the Free and Personal plans. You need the Business plan or higher, or a self-hosted WordPress install.
Edit the page, hover where you want the widget, click the insert point, and choose Code Block. Paste the iframe snippet and leave "Display Source" unticked.
Plan requirement: Code Blocks are only available on the Business plan and above. Personal plans can't embed iframes.
In the editor click Add Elements (the plus icon) → Embed Code → Embed HTML. A frame appears on the page; click Enter Code and paste the iframe snippet.
To make it responsive, set the Wix element to "Stretch" so it fills the column width.
Drag an Embed component onto the page from the Add panel, paste the iframe snippet into the code editor, and click Save. Publish the site to see it live – the embed only renders on the published version, not in Designer preview.
Plan requirement: Custom code requires a paid Site plan.
On a page: In the page editor, click the </> "Show HTML" button and paste the iframe snippet there.
On a theme section: Add a "Custom Liquid" section from the theme customiser and paste the iframe snippet.
Iframes pasted directly into product descriptions via the rich-text editor are sometimes stripped – use the HTML view or a Custom Liquid section for reliable rendering.
In the editor, type /html on a new line to insert an HTML card, then paste the iframe snippet.
Calculator widget
The calculator lets users enter a UK postcode or property details, then estimates heat pump sizing, solar PV output, battery savings, costs, and carbon impact. Configure it on the Calculator tab of your dashboard: brand colour, company name, which technologies to offer, whether nearby installers appear after the results, and an optional caveat banner.
<iframe src="https://widgets.karbonkit.com/widget-embed?type=lct-calculator&cid=YOUR_CID" width="100%" height="900" frameborder="0" style="border: none; border-radius: 8px;" allow="clipboard-write" ></iframe>
AR widget
The AR widget lets users preview a heat pump in their space using augmented reality. It works on iOS Safari and Android Chrome – no app download required.
<iframe src="https://widgets.karbonkit.com/widget-embed?type=heat-pump-ar&cid=YOUR_CID" width="100%" height="500" frameborder="0" style="border: none; border-radius: 8px;" allow="camera; xr-spatial-tracking; accelerometer; gyroscope; magnetometer; fullscreen" allowfullscreen ></iframe>
Set the model that loads first, your brand colour and the background colour on the AR tab of your dashboard. Keep the whole allow list: without camera and motion access the viewer loads, then fails when the visitor taps View in your room.
Installer finder widget
The installer finder lets users search for renewable energy installers near a UK postcode, ordered by distance. The directory is built from public records (Companies House, Google Places and installers’ own websites) and is not vetted by KarbonKit, so each result links to the MCS register for the visitor to check, and says where its technology tags came from. You can add your own suggested installers, shown first, or show only your own list.
<iframe src="https://widgets.karbonkit.com/widget-embed?type=installer-finder&cid=YOUR_CID" width="100%" height="700" frameborder="0" style="border: none; border-radius: 8px;" ></iframe>
Brand colour and company name are set in your dashboard, along with the options in the integration reference.
Tip: The installer finder also appears automatically after calculator results. Users who run a savings calculation will see nearby installers for their selected technologies.
Grant finder widget
The grant finder asks for a postcode and four quick questions (tenure, current heating fuel, EPC band, household circumstances) and shows which UK funding schemes the household may qualify for — the Boiler Upgrade Scheme, Warm Homes: Local Grant, ECO4, Home Energy Scotland, Nest, NISEP, 0% VAT relief, and the Smart Export Guarantee. Every result links to the official government page and shows the date the scheme data was last verified.
Local support (optional, off by default). From the Grant Finder tab of your dashboard you can add a link to the visitor’s council, and your own local schemes – council top-ups, local loans, advice services. Each local scheme can be limited to particular council areas and must have a date after which it stops showing. Local schemes are labelled as added by you; KarbonKit does not verify them. You can switch this on for a grant finder that is already embedded without changing your embed code. If you use a plain iframe with a fixed height, allow extra room for the new section.
<iframe src="https://widgets.karbonkit.com/widget-embed?type=grant-finder&cid=YOUR_CID" width="100%" height="900" frameborder="0" style="border: none; border-radius: 8px;" ></iframe>
Brand colour and company name are set in your dashboard, along with the options in the integration reference.
How the data stays current: scheme details are verified against official sources (gov.uk, Ofgem, Home Energy Scotland, gov.wales, NIHE) on a rolling review cycle. Schemes that have closed are hidden automatically, and if a scheme changes before our next review the widget tells users to confirm on the official page.
Boiler escape plan widget
The boiler escape plan walks a household through a short readiness check (postcode → EPC match → boiler age → home plans → motivation) and generates a personalised plan with an optional calendar reminder.
It covers mains gas, heating oil and LPG. Off-gas households get their own arithmetic rather than gas figures with the labels changed: heating oil emits about 35% more CO2 per kWh than mains gas, oil boilers run at a lower real-world seasonal efficiency, and the lock-in warning reflects that a breakdown means another oil boiler because there is no gas grid to fall back on. Worth knowing if your audience is rural – this is where the case for switching is strongest.
<iframe src="https://widgets.karbonkit.com/widget-embed?type=boiler-escape-plan&cid=YOUR_CID" width="100%" height="1000" frameborder="0" style="border: none; border-radius: 8px;" ></iframe>
The widget is full-width and resizes its internal layout to fit. For mobile-heavy audiences, allow at least 1100px of height to avoid an internal scrollbar on the questions step.
Sound simulator widget
The sound simulator plays a real heat pump recording and uses the visitor's microphone to measure decibel level from different distances. Browsers require microphone permission, so the iframe needs an allow="microphone" attribute.
<iframe src="https://widgets.karbonkit.com/widget-embed?type=sound-simulator&cid=YOUR_CID" width="100%" height="700" frameborder="0" style="border: none; border-radius: 8px;" allow="microphone" ></iframe>
HTTPS only: Browsers block microphone access on non-secure pages. The parent site must be served over HTTPS for the dB measurement to work.
3D house tour widget
An interactive 3D tour of a heat pump home: outdoor unit, pipework with animated heat flow, hot water cylinder, radiators, solar panels, and home battery. Users take a guided 9-stop tour or explore freely, with a day/night toggle showing the battery at work after dark. Add the allow attributes so users can enter fullscreen. (The legacy type=system-diagram also renders this widget.)
<iframe src="https://widgets.karbonkit.com/widget-embed?type=house-tour&cid=YOUR_CID" width="100%" height="660" frameborder="0" style="border: none; border-radius: 8px;" allowfullscreen allow="fullscreen" ></iframe>
Legacy URL parameters
Snippets from the dashboard carry only type and cid; everything else comes from the configuration saved against the config ID. The other parameters below are read only by older snippets whose cid was not issued by the dashboard. With a dashboard config ID they are ignored.
| Parameter | Type | Default | Description |
|---|---|---|---|
cid | string | – | Config ID from your dashboard. All settings come from it. Required for the calculator and AR visualiser; see the integration reference for the others. |
type | string | heat-pump-ar | Widget type, from the integration reference. The type saved against a config ID takes precedence. |
model | number | 7 | AR visualiser only: the model to load first, used when the saved configuration names none. |
primary | hex | #22c55e | Primary brand colour (URL-encoded). |
secondary | hex | #ffffff | Background colour (URL-encoded). |
tier | string | – | Ignored. Kept here because older snippets carry it; settings come from the config ID. |
embed | boolean | – | No effect. Older snippets carry it. |
company | string | – | Company name shown in calculator header. |
lcts | string | all | Comma-separated technologies: heatPump, solarPV, battery. |
caveat | string | – | Calculator only. Custom safety/caveat banner shown above the calculator (URL-encoded, max 240 chars). Useful for steering users toward your home-assessment process. |
Collecting enquiries (optional)
The savings calculator and the boiler escape plan can show a short "get in touch" form after a visitor's results. It is off by default and nothing changes on your site until you turn it on – including on embeds that are already live. Switch it on per widget under Leads in your dashboard, give an address for the enquiries to go to, and name your organisation so visitors know who they are agreeing to hear from.
What you get. Name, email, an optional phone number, postcode, anything they typed, and a summary of what the widget worked out – the readiness score and weakest links for the boiler plan, the technologies and estimated savings for the calculator. That last part is the useful bit: it tells you whether someone needs a survey booked or a cylinder problem solving first, before you pick up the phone.
Where it goes. Straight to the address you set, with the visitor's address as the reply-to, and into your Leads tab. The dashboard copy is the durable one – if a notification email bounces, the enquiry is still there. Export the lot to CSV whenever you want it in your own system.
Your responsibility. People are consenting to hear from you, so your own privacy notice needs to cover contacting visitors who use the widget. We keep our copy for 12 months and then delete it, we never market to your visitors, and we pass enquiries to nobody else. See privacy for the section written for a data protection officer.
There is nothing to change in your embed code. The form is controlled entirely by the widget's saved configuration, so turning it on or off takes effect on your live page without you touching the snippet.
Auto-resizing iframes (optional)
By default the iframe stays the height you set on it, which means picking a value tall enough to fit the widget on the smallest screen you care about. On mobile the calculator and boiler escape plan can run past 1500px once content stacks vertically, so a desktop-tuned 700px will cut off mid-form.
KarbonKit widgets postMessage their current content height to the parent window on every resize. Add this small listener anywhere on the page and the iframe will track its content exactly – no scrollbar, no empty space, no fixed-height guessing. The script-tag embed does this for you.
<iframe
id="kk-calculator"
src="https://widgets.karbonkit.com/widget-embed?type=lct-calculator&cid=YOUR_CID"
width="100%"
height="900"
frameborder="0"
style="border: none; border-radius: 8px;"
></iframe>
<script>
window.addEventListener('message', function (event) {
if (event.data && event.data.type === 'karbonkit:resize') {
var iframe = document.getElementById('kk-calculator');
if (iframe && event.source === iframe.contentWindow) {
iframe.style.height = event.data.height + 'px';
}
}
});
</script>The check on event.source is important if you have more than one widget on the page – it scopes each height message to the right iframe. Always check the type too, so unrelated postMessages from other scripts don't accidentally resize the widget.
The height attribute on the <iframe> still matters as a fallback for the brief window before the first message arrives and for users who load with JavaScript disabled. Set it to a sensible default (the desktop height of the widget is a good start).
In a plain iframe the widget learns your page’s origin from the browser’s Referer header and sends height messages only to that origin. A page served with Referrer-Policy: no-referrer gets none, so use the script tag there.
Troubleshooting
cid parameter. Open your browser's developer console (F12) and check the Network tab – a 404 on /api/widget/.../config means the config ID is wrong or the widget has been deleted. Generate a fresh embed snippet from the dashboard.Either increase the iframe height attribute (the calculator and boiler escape plan typically need ~1500–2000px on mobile once content stacks vertically), or add the small auto-resize listener described in the Auto-resizing iframes section above.
Mobile Safari in particular doesn't reliably allow scrolling inside an iframe whose content overflows, so on mobile-heavy audiences the auto-resize listener is the more robust option.
allow="xr-spatial-tracking" and the parent page is served over HTTPS.allow="microphone" attribute. The script-tag loader sets this for you. If you are pasting a raw iframe, add it yourself – and note that page builders like Wix run your snippet inside their own iframe, so the permission has to be granted at every level of nesting or it gets dropped. Where you cannot control the outer iframe, camera and microphone widgets may not work at all on that platform.https://widgets.karbonkit.com and https://karbonkit.com to your frame-src directive.embed.js. If you copied a snippet before that fix, the loader is cached on your site – hard-refresh, purge your CDN cache, and re-copy the snippet from your dashboard. The loader no longer makes any network request of its own, so it cannot fail this way again. If a widget still will not appear, the message now comes from the widget itself and says which of the two things went wrong: the config id no longer matches a widget, or our API was unreachable.Check three things in the Leads tab of your dashboard. First, enquiry collection is off by default and has to be switched on for that specific widget – not for your account. Second, it needs a valid address to send enquiries to; without one it stays off, because collecting details with nowhere to send them would lose them. Third, it only applies to widgets saved in your dashboard – a demo embed with no cid, or one that only carries settings in the URL, has no owner to route an enquiry to and will never show the form.
If the widget on the Leads tab says "Collecting" and the form still isn't there, hard-refresh the page your widget is on – the widget fetches its configuration on load.
widgets.karbonkit.com if necessary.Frequently asked questions
width="100%" and they will fill whatever space you give them. On mobile devices, the layout stacks vertically automatically.<iframe> tag, it works.Ready to embed?
Sign up for a free account to configure your widgets visually and get a copy-paste embed code.