Embedding Guide

How It Works

Every BarBuilder progress bar is a standard SVG image served from a URL. This means you can embed it anywhere that supports images — just point an <img> tag or Markdown image syntax at the URL.

Key concept: The URL is the configuration. Change the URL parameters and the image changes instantly. No JavaScript, no API keys, no build steps.

Start by building your bar with the visual builder, then copy the URL, Markdown, or HTML snippet.

GitHub README

GitHub renders Markdown images natively, making BarBuilder a perfect fit for README badges and status indicators.

Basic usage

![Build](https://api.barbuilder.dev/percentage/100?style=badge&color=4c1&label=Build)
![Coverage](https://api.barbuilder.dev/percentage/87?style=badge&color=32cd32&label=Coverage)
![Rating](https://api.barbuilder.dev/icon/4.5/5?shape=star&color=ffd700&label=Rating)

Linking to a page

Wrap the image in a Markdown link to make it clickable:

[![Build Status](https://api.barbuilder.dev/percentage/100?style=badge&color=4c1&label=Build)](https://github.com/your/repo/actions)

Multiple badges in a row

Place them on the same line with no blank lines between:

![Build](https://api.barbuilder.dev/percentage/100?style=badge&color=4c1&label=Build) ![Tests](https://api.barbuilder.dev/percentage/94?style=badge&color=1e90ff&label=Tests) ![Coverage](https://api.barbuilder.dev/percentage/87?style=badge&color=32cd32&label=Coverage)

GitHub caching

GitHub proxies external images through camo.githubusercontent.com. This proxy caches images, so changes to your bar may take a few minutes to appear. To force a refresh:

Append a cache-busting query parameter, e.g. &v=2
Or wait for GitHub's cache to expire (typically a few minutes)

HTML / Websites

Use a standard <img> tag. The SVG scales cleanly to any size.

Basic embed

<img src="https://api.barbuilder.dev/percentage/75?style=pill&color=dodgerblue&label=Progress"
     alt="75% progress"
     width="200">

With inline styles

<img src="https://api.barbuilder.dev/percentage/75?style=pill&color=dodgerblue"
     alt="75% progress"
     style="width: 100%; max-width: 300px; height: auto;">

As a background image (CSS)

SVGs can also be used as CSS background images, though <img> is usually simpler:

.progress-badge {
  width: 200px;
  height: 20px;
  background: url('https://api.barbuilder.dev/percentage/75?style=pill&color=dodgerblue') no-repeat;
  background-size: contain;
}

Markdown

Standard Markdown image syntax works in any renderer (GitHub, GitLab, Bitbucket, Docusaurus, MkDocs, etc.).

![Progress](https://api.barbuilder.dev/percentage/75?style=pill&color=dodgerblue&label=Progress)

With a title tooltip

![Progress](https://api.barbuilder.dev/percentage/75?style=pill&color=dodgerblue "75% complete")

Reference-style (cleaner for multiple bars)

![Build Status][build-badge]
![Test Coverage][coverage-badge]

[build-badge]: https://api.barbuilder.dev/percentage/100?style=badge&color=4c1&label=Build
[coverage-badge]: https://api.barbuilder.dev/percentage/87?style=badge&color=32cd32&label=Coverage

Notion

Notion supports external image embeds. There are two approaches:

Image block

Type /image to create an image block
Select Embed link
Paste the BarBuilder URL

Inline embed

Type /embed
Paste the BarBuilder URL
Notion will render the SVG inline

Tip: Notion caches external images aggressively. If you update the URL parameters, you may need to remove and re-add the block to see changes.

Confluence

Atlassian Confluence supports external images in both Cloud and Server editions.

Confluence Cloud

Type / to open the insert menu
Select External image (or Image → Web URL)
Paste the BarBuilder URL

Confluence wiki markup

!https://api.barbuilder.dev/percentage/75?style=pill&color=dodgerblue&label=Progress!

Email

Most email clients support external images via <img> tags.

<img src="https://api.barbuilder.dev/percentage/75?style=pill&color=dodgerblue&label=Progress"
     alt="75% progress"
     width="200"
     style="display:block;">

Note: Some email clients block external images by default. Always include a meaningful alt attribute as a fallback. Outlook in particular may require a fixed width attribute rather than CSS styling.

Responsive Sizing

BarBuilder SVGs scale cleanly. Use CSS to make them responsive:

Full width (capped)

<img src="https://api.barbuilder.dev/percentage/75?style=pill&color=dodgerblue&width=400"
     alt="Progress"
     style="width: 100%; max-width: 400px; height: auto;">

Using the width parameter

The width query parameter controls the SVG's internal dimensions (50–500px). The HTML width attribute or CSS controls how large it appears on screen. For the sharpest result, match the two:

<!-- SVG is 300px wide internally, displayed at 300px -->
<img src="https://api.barbuilder.dev/percentage/75?width=300"
     width="300">

You can also display a wider SVG at a smaller size — it will scale down crisply because it's a vector image.

Dynamic Values

Because the value is part of the URL, you can generate URLs dynamically in any language or framework.

JavaScript

const value = 75;
const url = `https://api.barbuilder.dev/percentage/${value}?style=pill&color=dodgerblue`;
document.getElementById('progress').src = url;

Python (in a Jupyter notebook or README generator)

value = 75
url = f"https://api.barbuilder.dev/percentage/{value}?style=pill&color=dodgerblue"
markdown = f"![Progress]({url})"

CI/CD pipelines

Update your README badge URL as part of your build process:

# Bash — update a badge in README after running tests
COVERAGE=$(cat coverage.txt)
sed -i "s|/percentage/[0-9]*|/percentage/${COVERAGE}|" README.md

Remember: BarBuilder URLs are cached for 1 year. If you change the value in the URL, it's a new URL and will be generated fresh. The old URL continues serving the old value from cache.

Dark Mode

Use ?theme=dark to generate bars with dark-friendly colours. This is ideal for dark-mode documentation, dashboards, and READMEs.

![Progress](https://api.barbuilder.dev/percentage/65?style=pill&color=4c71ff&theme=dark&label=Progress)

Serving different themes with CSS

Use the <picture> element to show different bars based on the user's colour scheme preference:

<picture>
  <source media="(prefers-color-scheme: dark)"
          srcset="https://api.barbuilder.dev/percentage/75?theme=dark&color=4c71ff">
  <img src="https://api.barbuilder.dev/percentage/75?color=44cc11"
       alt="75% progress"
       width="200">
</picture>

GitHub dark mode

GitHub supports the <picture> element in READMEs, so you can serve the right theme automatically:

<picture>
  <source media="(prefers-color-scheme: dark)"
          srcset="https://api.barbuilder.dev/percentage/75?style=badge&color=4c71ff&theme=dark&label=Build">
  <img src="https://api.barbuilder.dev/percentage/75?style=badge&color=4c1&label=Build"
       alt="Build status">
</picture>

Troubleshooting

Image not updating after URL change

BarBuilder caches successful responses for 1 year. Each unique URL is a separate cache entry, so changing any parameter creates a fresh image. If you're seeing a stale image:

Browser cache: Hard-refresh the page (Ctrl+Shift+R)
GitHub/Notion cache: These platforms proxy images through their own CDN. Wait a few minutes or add a cache-busting parameter (e.g. &v=2)

Image appears as a broken icon

Check the URL is correct — try opening it directly in a browser
Ensure the embedding platform allows external images
Some corporate firewalls block external image requests

Image looks blurry

BarBuilder generates vector SVGs that are resolution-independent. If the image looks blurry, it's likely being rasterised at too small a size. Try:

Increasing the width query parameter
Ensuring the HTML display size matches the SVG width
Checking that the embedding platform supports SVG (most do)

Red error bar instead of my progress bar

BarBuilder returns errors as red SVG images with a message describing the problem. Open the URL directly in a browser to read the error message. Common causes:

Percentage value outside 0–100
Invalid colour name or hex value
Unknown style name

See the API error reference for the full list.