You have scanned your site, you have a grade, and now you want to show it. This tutorial covers every practical way to embed a carbon badge — from the simplest possible HTML one-liner to framework-specific implementations in WordPress, Shopify, Next.js, Hugo, and Jekyll. Copy-paste the snippet that matches your stack and you are done.
If you are not sure what a carbon badge is or why you would want one, the complete carbon badge guide covers that ground. This post assumes you already know what you want and just need the code.
Quick Overview: What You Are Embedding
A carbon badge from Carbon Badge is an SVG image served over HTTPS from carbon-badge.com. It is dynamic — it pulls the most recent scan result for your domain and renders it in real time. The badge SVG is approximately 1 KB, has no JavaScript dependency by default, and is served with a 24-hour CDN cache (which means CORS preflight is cached too, not re-executed on every load).
The badge URL pattern is:
https://carbon-badge.com/api/badge/{your-domain}.svgReplace {your-domain} with your actual domain — for example acme.com — without https:// and without a trailing slash. That is the URL you will use in every embedding method below.
Step 1 — Scan Your Website
Before you can embed anything, your domain needs to be registered and scanned. Go to carbon-badge.com, enter your URL, and run the scan. It takes 10–20 seconds. Once it completes, you will see your grade (A through F) and your CO₂ per pageview figure.
Run the scan on the page you care most about. For most sites that is the homepage. For e-commerce it might be your best-selling product page. The badge will reflect whichever URL you register — so pick the one your visitors actually land on.
If you have not scanned yet, do that first and come back here with your domain ready.
Step 2 — Choose a Plan
This step matters for what you get to embed.
The free plan gives you a static badge: a snapshot of your score at the time of the scan, served as a fixed SVG. It is honest — it shows your score — but it does not update automatically when your site changes.
The Pro plan (and above) gives you a dynamic badge: it re-scans your site on a schedule (weekly on Pro) and the badge SVG reflects the most recent result. If you ship a heavy redesign that pushes you from Grade B to Grade D, the badge shows Grade D within a week. That accountability is what makes the badge worth displaying in the first place.
You can compare the plans at carbon-badge.com/en/pricing/. For most individual sites and small studios, free is fine to start. Upgrade when you want the badge to stay current automatically.
Step 3 — Get Your Embed Code
Once your site is registered, log into your Carbon Badge dashboard. Under your site's entry, there is an "Embed" section with pre-generated snippets for the most common methods. Copy the one that matches your setup, or use the patterns below — they are the same thing.
Embedding Methods
Method A — HTML Image Tag (Simplest)
This works on any website, in any templating language, without any build tools. It is a plain anchor wrapping an image. Copy-paste this into your footer, your about page, or wherever you want the badge to appear:
<a href="https://carbon-badge.com/en/scan/yoursite.com/"
rel="noopener noreferrer"
title="View carbon footprint report for yoursite.com">
<img src="https://carbon-badge.com/api/badge/yoursite.com.svg"
alt="Carbon Badge — website carbon footprint grade"
width="200"
height="56"
loading="lazy">
</a>Replace both instances of yoursite.com with your actual domain. The loading="lazy" attribute defers the badge request until it scrolls into view — relevant if you place it in a footer that most users never reach. The explicit width and height prevent layout shift.
That is it. No configuration, no API keys, no JavaScript. The browser fetches the SVG exactly like any other image.
Method B — JavaScript Snippet (Auto-Detects Domain)
If you run multiple pages on the same domain and want the badge to auto-detect the current domain rather than hardcoding it, use the JavaScript embed. This is useful for multi-page sites where you include a shared footer component without wanting to pass a domain variable into it.
<!-- Place this in your footer, before </body> -->
<div id="carbon-badge"></div>
<script src="https://carbon-badge.com/api/badge-embed.js" async></script>The script reads window.location.hostname, constructs the correct badge URL, and injects the badge image into #carbon-badge. The async attribute means it does not block page rendering. The script itself is under 2 KB minified and gzipped.
If you need to override the domain (for example, on a staging subdomain that points to your production scan), add a data-domain attribute:
<div id="carbon-badge" data-domain="yoursite.com"></div>
<script src="https://carbon-badge.com/api/badge-embed.js" async></script>Method C — WordPress
There are two sensible approaches depending on your theme setup.
Option 1 — Footer widget (no code). In your WordPress admin, go to Appearance → Widgets → Footer area. Add a Custom HTML widget. Paste the HTML image tag from Method A. Save. Done.
Option 2 — Theme customizer. Appearance → Customize → Additional CSS will not work here (you need HTML, not CSS). Instead, go to Appearance → Customize → Footer → Footer HTML (available in most themes) and paste the snippet there.
Option 3 — Direct in footer.php. If you are editing a child theme, open footer.php and add the snippet just before the </body> tag:
<!-- In wp-content/themes/your-child-theme/footer.php -->
<a href="https://carbon-badge.com/en/scan/yoursite.com/"
rel="noopener noreferrer">
<img src="https://carbon-badge.com/api/badge/yoursite.com.svg"
alt="Carbon Badge"
width="200" height="56"
loading="lazy">
</a>
</body>
</html>If your theme uses full site editing (FSE/block themes), add the badge using the Site Editor: go to Appearance → Editor → Template Parts → Footer. Insert an HTML block with the snippet.
Method D — Shopify
In Shopify, all themes share a root layout file called theme.liquid. Open it via Online Store → Themes → Actions → Edit Code → Layout → theme.liquid. Find the closing </body> tag and paste the badge snippet just before it:
<!-- Carbon badge — paste before </body> in theme.liquid -->
<a href="https://carbon-badge.com/en/scan/yourstore.myshopify.com/"
rel="noopener noreferrer"
style="display:inline-block;">
<img src="https://carbon-badge.com/api/badge/yourstore.myshopify.com.svg"
alt="Carbon Badge"
width="200" height="56"
loading="lazy">
</a>Use your custom domain in the badge URL if you have one connected (e.g., yourstore.com rather than yourstore.myshopify.com) — but make sure that is the domain you scanned and registered in Carbon Badge.
Method E — Next.js / React
In a Next.js project, use the built-in Image component for the badge. You need to add Carbon Badge's domain to the images.remotePatterns list in next.config.js first:
// next.config.js
module.exports = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 'carbon-badge.com',
pathname: '/api/badge/**',
},
],
},
};Then in your footer component:
// components/Footer.tsx
import Image from 'next/image';
export function CarbonBadge() {
const domain = 'yoursite.com';
return (
<a
href={`https://carbon-badge.com/en/scan/${domain}/`}
rel="noopener noreferrer"
title="Website carbon footprint report"
>
<Image
src={`https://carbon-badge.com/api/badge/${domain}.svg`}
alt="Carbon Badge"
width={200}
height={56}
loading="lazy"
unoptimized
/>
</a>
);
}The unoptimized prop is important here. Next.js image optimisation rewrites URLs to go through its own proxy — which would break the dynamic badge URL. Set unoptimized to serve the badge SVG directly from Carbon Badge's CDN, as intended.
If you are on plain React (not Next.js), skip the Image component and use a standard <img> tag instead — same as Method A.
Method F — Hugo
In Hugo, create a partial at layouts/partials/carbon-badge.html:
{{/* layouts/partials/carbon-badge.html */}}
<a href="https://carbon-badge.com/en/scan/{{ .Site.Params.domain }}/"
rel="noopener noreferrer">
<img src="https://carbon-badge.com/api/badge/{{ .Site.Params.domain }}.svg"
alt="Carbon Badge"
width="200" height="56"
loading="lazy">
</a>Set your domain in config.toml (or hugo.toml):
[params]
domain = "yoursite.com"Then include the partial in your base layout:
{{/* layouts/_default/baseof.html */}}
{{ partial "carbon-badge.html" . }}
</footer>Method G — Jekyll
In Jekyll, add an include file at _includes/carbon-badge.html:
<!-- _includes/carbon-badge.html -->
<a href="https://carbon-badge.com/en/scan/{{ site.domain }}/"
rel="noopener noreferrer">
<img src="https://carbon-badge.com/api/badge/{{ site.domain }}.svg"
alt="Carbon Badge"
width="200" height="56"
loading="lazy">
</a>Add domain: yoursite.com to your _config.yml. Then in your layout file:
<!-- _layouts/default.html -->
{% include carbon-badge.html %}
</footer>Customization Options
The badge endpoint accepts a few query parameters for visual customization:
<!-- Dark theme, small size -->
<img src="https://carbon-badge.com/api/badge/yoursite.com.svg?theme=dark&size=small"
alt="Carbon Badge" width="120" height="40" loading="lazy">
<!-- Light theme, large size -->
<img src="https://carbon-badge.com/api/badge/yoursite.com.svg?theme=light&size=large"
alt="Carbon Badge" width="300" height="84" loading="lazy">Available options:
- theme:
light(white background) ordark(dark background). Default islight. - size:
small(120×40px),medium(200×56px, default), orlarge(300×84px). Since it is an SVG, these are reference dimensions — you can also scale it with CSS.
Pro plan users also have access to a monochrome variant and a minimal variant (grade letter and grams only, no background) via the dashboard embed generator.
Troubleshooting Common Issues
Badge shows a broken image icon
Your domain is probably not registered in Carbon Badge yet, or the initial scan has not completed. Make sure you have run a scan at carbon-badge.com for the exact domain you are using in the badge URL. Check that the domain in the URL matches the one you scanned — including or excluding www.
Content Security Policy (CSP) blocks the badge
If your site runs a strict CSP, you need to whitelist Carbon Badge's domain in your img-src directive:
Content-Security-Policy: img-src 'self' https://carbon-badge.com;If you use the JavaScript snippet (Method B), you also need to add Carbon Badge to script-src:
Content-Security-Policy: script-src 'self' https://carbon-badge.com; img-src 'self' https://carbon-badge.com;Badge is cached and not updating after a rescan
The badge SVG is cached at the CDN edge for 24 hours. After a new scan completes, the updated badge propagates within 24 hours. If you need to verify the new score immediately, open the badge URL directly in a browser with cache disabled (Ctrl+Shift+R / Cmd+Shift+R) or use a fresh incognito window. The badge on your live site will update at the next CDN cache expiry.
Wrong domain in the badge
If your domain redirects — for example www.yoursite.com redirects to yoursite.com — make sure the domain in your badge URL matches the registered domain exactly, after any redirects. The badge URL does not follow redirects; it serves the data for the literal domain string you provide.
Next.js Image component 400 error
This happens when you forget the unoptimized prop or the remotePatterns config. Double-check both — the Image component will throw a 400 if it tries to proxy an external URL that is not in remotePatterns.
Performance Impact
A few concrete numbers, since this comes up:
- SVG size: approximately 900 bytes to 1.4 KB depending on the grade and gram figure rendered (longer strings = slightly larger SVG).
- CDN cache: 24-hour TTL. After the first request from a given CDN edge node, subsequent requests are served from cache — no origin roundtrip, no re-render.
- CORS: Carbon Badge's badge endpoint sends permissive CORS headers (
Access-Control-Allow-Origin: *). CORS preflight results are cached alongside the SVG response, so there is no per-request preflight overhead after the first hit. - Lazy loading: with
loading="lazy", the badge request is deferred until the element enters the viewport. For footer badges, this means most users never trigger the request at all — the badge loads only when someone scrolls to the bottom. - Render blocking: none. The badge is a standard image resource and does not block the critical rendering path regardless of where in the HTML it appears.
In practical terms, the badge adds negligible weight to your page. It is smaller than a favicon.
SEO Benefits of Displaying a Badge
Displaying a carbon badge has a few SEO-adjacent effects worth knowing about:
Trust signals. A third-party verified score — especially one that links to a detailed report — is a concrete trust signal in an era where vague sustainability claims are everywhere. Users who notice it read it as proof, not aspiration. That distinction matters for conversion and for the E-E-A-T signals that inform how Google evaluates your site's credibility.
Core Web Vitals alignment. The work required to achieve a Grade A badge — lighter images, leaner JavaScript, efficient caching — is the same work that improves Largest Contentful Paint and Total Blocking Time. Better CWV scores have a documented positive correlation with search rankings. The badge is a byproduct of doing the performance work; the ranking benefit accrues regardless of whether you display the badge.
Page load speed. Faster pages rank better. A Grade A site typically loads in under 2 seconds on a median mobile connection. A Grade F site is often 5–8 seconds. The SEO benefit is not from the badge itself — it is from the lighter site that earns the grade.
Sustainability-related search queries. If your site covers sustainable products, ESG services, or green technology, having verifiable sustainability credentials adds relevance signals. A carbon badge gives you something factual to reference in your content — "we run on a Grade A carbon footprint" — which is more substantive than generic sustainability copy.
For the full picture on why the grade matters for your broader digital footprint, the complete carbon reduction guide walks through the optimisations that drive grade improvement. The website carbon footprint primer covers the measurement methodology if you want to understand what the gram figure actually represents. And for a technical deep dive into how your score is calculated, read our SWDM v4 explainer.