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.
Every snippet, setting and framework example (React, Next.js, WordPress) is in the complete integration guide.
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_CONFIG_ID with the config ID from your dashboard.
<iframe src="https://widgets.karbonkit.com/widget-embed?type=lct-calculator&cid=YOUR_CONFIG_ID" 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, grouped by the question it helps a household answer, 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) |
|---|---|---|---|---|---|---|---|
| Is it right for my home? | |||||||
| 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 (paid feature, 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 (paid feature, off by default). The widget keeps its own colours; brand colour is used on the enquiry form and footer link |
| Radiator check | radiator-check | data-karbonkit data-config-id | 1100px | Script tag: yes. Iframe: only with the listener below | none needed | Optional – without one, default colours and no company name | Brand colour; company name (shown as "Provided by …"); enquiry collection (paid feature, off by default) |
| How do I get it done? | |||||||
| 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 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) |
| What is it like to live with? | |||||||
| Home energy technology 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 technologies to show (heat pumps, hot water cylinder, home batteries, solar inverter); which model loads first |
| Sound simulator | sound-simulator | data-karbonkit data-config-id | 1000px | 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 …"); brand colour for its buttons and highlights |
| 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 (shown as "Provided by …"); where the last button goes |
| Watt's House | watts-house | 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 (shown as "Provided by …"); where the last button goes |
Options live in the dashboard, not the snippet. They are saved against your config ID when you press Create widget, which is when the snippet appears. To change a widget already on your site, choose it under Your saved widgets on its dashboard tab and click Edit; the change reaches your live page without editing it. Delete, on the same row, makes every page with that snippet show “Widget not found”; you can restore it from Recently deleted for 30 days. 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 nothing can be set for the widget in the dashboard: no company name, no enquiry collection and no 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.
Using another platform, or stuck? Ask an AI assistant
Copy a ready-made question for ChatGPT, Claude or any other AI chat. It includes your code and asks for click-by-click steps for your website. Tell it your website’s address and an assistant that can open web pages can check what the site is built with.
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_CONFIG_ID" width="100%" height="900" frameborder="0" style="border: none; border-radius: 8px;" allow="clipboard-write" ></iframe>
Home energy technology visualiser
The home energy technology visualiser lets users preview a heat pump, a hot water cylinder, a home battery or a solar inverter in their space at true size using augmented reality, on the floor or a wall. It works on iOS Safari and Android Chrome – no app download required. In the dashboard you choose which of the four to show.
<iframe src="https://widgets.karbonkit.com/widget-embed?type=heat-pump-ar&cid=YOUR_CONFIG_ID" 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 and installers’ own websites) and is not vetted by KarbonKit, so each result links to the MCS register for the visitor to check. 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_CONFIG_ID" 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, the Smart Export Guarantee and the Warm Homes Loan Scheme (low- and no-interest loans across the UK). 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_CONFIG_ID" 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_CONFIG_ID" 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.
Radiator check widget
"Will I have to change all my radiators?" is the objection after price. The radiator check answers it without a tape measure: the visitor says how their boiler's heating control looks (degrees on a screen, a dial numbered 1–6, an unmarked dial, or "never changed it") and where it is set, which rooms they have and which are not warm enough on a cold day, and the radiator type in each room (single, double or triple panel, column, towel rail – told apart by how far it sticks out from the wall) and how thick its pipes are. A room can hold several radiators. It then shows which radiators would need changing for a heat pump designed to 40, 45, 50 or 55°C, which are a straight swap for a deeper radiator in the same wall space, which need more wall space, and the flow temperature the home could run at as it stands.
It is a ratio method: BS EN 442 rates every radiator at ΔT50 and output scales with ΔT to the power 1.3, so the length of a radiator cancels out and only its type matters. It assumes each radiator is only just big enough for its room today, so the answer leans cautious. A per-room comfort question corrects that, and so does a household that has already run the boiler lower in cold weather. When the answer rests on guesses, the widget suggests a week-long boiler turn-down test at a named setting, with a calendar reminder to come back. Thin (microbore) pipes are flagged for the installer to check; they do not change the verdict. It is a screening estimate ahead of an MCS installer's room-by-room heat-loss survey, and says so.
<iframe src="https://widgets.karbonkit.com/widget-embed?type=radiator-check&cid=YOUR_CONFIG_ID" width="100%" height="1100" frameborder="0" style="border: none; border-radius: 8px;" ></iframe>
The questions come in four short steps that each fit a phone screen; the results page runs to about 1500px on mobile with six rooms, so allow at least 1100px of height or add the auto-resize listener. Brand colour and company name are set in your dashboard. Enquiry collection is available on this widget – see Collecting enquiries.
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_CONFIG_ID" width="100%" height="1000" 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
A 3D cutaway of an ordinary 1930s semi that runs entirely on electricity: heat pump, hot water cylinder, radiators and controls, solar panels, home battery, car charging and an induction hob – twenty things in all, each explained in plain English with its sources. A guided tour flies through twelve of them, then visitors can carry on through the rest or pick a room. An afternoon/evening switch shows the battery and cheap overnight hours at work, and a plain-text list covers devices that cannot draw 3D. The 3D view downloads only when the visitor presses start. The card at the end offers one button: by default to KarbonKit’s boiler escape plan, or in the dashboard choose your own page (and button text) or no button. 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_CONFIG_ID" width="100%" height="660" frameborder="0" style="border: none; border-radius: 8px;" allowfullscreen allow="fullscreen" ></iframe>
Watt’s House widget
The same all-electric house as the 3D house tour, explored with Watt, a ginger cat. Visitors tap where he should go – upstairs too – and whatever he sits beside is explained in plain English, with its sources; or they follow him on a ten-stop tour. It covers the same twenty topics, in a friendlier way, for a general audience, families and schools. Same size and permissions as the 3D house tour.
<iframe src="https://widgets.karbonkit.com/widget-embed?type=watts-house&cid=YOUR_CONFIG_ID" 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. Older snippets carry more parameters. Since September 2026 the ones that set branding or text (primary, secondary, company, lcts, caveat) are ignored everywhere, and the calculator and AR visualiser need a config ID issued by the dashboard. To change how an older embed looks, copy a fresh snippet.
| Parameter | Type | Default | Description |
|---|---|---|---|
cid | string | – | Config ID from your dashboard. All settings come from it. Required for the calculator and AR visualiser; the other widgets render with default settings without one. |
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, secondary, company, lcts, caveat | – | – | Ignored. Older snippets carry them; branding and text are set in the dashboard. |
tier | string | – | Ignored. Kept here because older snippets carry it; settings come from the config ID. |
embed | boolean | – | No effect. Older snippets carry it. |
Collecting enquiries (optional)
The savings calculator, the boiler escape plan and the radiator check 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, on its tab or 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.
Enquiry collection is a paid feature. Paid plans are not on sale yet. If your organisation is small or unfunded and enquiries would help, email hello@karbonkit.com and we can switch it on for you.
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, the room-by-room verdict for the radiator check. 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_CONFIG_ID"
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 more reliable.
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.Enquiry collection is a paid feature, so on a free account the form is never shown. Otherwise, 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.