Three ways a component gets into your page

A widget is a single .html file: inline CSS, inline JavaScript, no dependencies, no CDN, no build step, no webfont requests. It reads its configuration from a JSON script tag or from the URL, renders itself, and never contacts a server again.

That single file is what makes both hosted and offline delivery possible without the two versions drifting apart. The /embed URL streams it with your parameters appended to the query string. The download endpoint streams the same bytes with your parameters baked into the file, because a sandboxed block has no URL to read them from.

GET /embed/pomodoro-timer
      ?work=25&short=5
      &accent=%23e03e3e

→ streams pomodoro-timer.html
→ /embed block iframes it
→ we can ship fixes to you

GET /api/widget/pomodoro-timer
      ?work=25&short=5

→ same HTML, config injected as
  <script id="bk-config">
→ /html block renders it
→ works offline, forever

The oldest trick in the book, and still the fastest. Notion's /embed block iframes any URL that allows framing. We serve widgets with Content-Security-Policy: frame-ancestors * and no X-Frame-Options, so Notion can wrap them.

1. 1
   Copy the URL from any component page

   The configurator writes every control into the query string as you change it, so the URL you copy is the URL you configured.

   https://notionarena.vercel.app/embed/pomodoro-timer?work=25&short=5&accent=%23e03e3e
2. 2
   In Notion, type /embed and press Enter

   Choose “Embed link”, not “Upload”, which is the HTML block path.

3. 3
   Paste and resize

   Drag the block's bottom edge to set the height. Notion remembers the size per block, and the widget's layout adapts.

Notion 3.6 shipped a real HTML block. It is not an iframe of a URL. it is a file you upload, stored in Notion's own file storage and rendered in a sandboxed frame with no address. The /html slash command creates one by hand, and the Notion API creates one through the File Upload endpoints.

Because the sandbox has no URL, configuration cannot come from a query string. It is injected into the file at download time as a JSON script tag that the widget reads before it renders:

<!-- injected just before </head> -->
<script id="bk-config" type="application/json">
  {"work":25,"short":5,"accent":"#e03e3e","theme":"auto"}
</script>

Installing one with the API

Three requests. This is the flow Notion documents for HTML blocks and the one Notion MCP uses internally. It just is not obvious from the block reference, because the embed block type does the double duty.

# 1: reserve
curl -X POST https://api.notion.com/v1/file_uploads \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" -d '{}'

# 2: upload the bytes to the returned upload_url
curl -X POST "$UPLOAD_URL" \
  -H "Content-Type: text/html" \
  --data-binary @pomodoro-timer.html

# 3: append the block
curl -X PATCH \
  https://api.notion.com/v1/blocks/$PAGE_ID/children \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [{
      "object": "block",
      "type": "embed",
      "embed": {
        "file_upload": { "id": "'"$UPLOAD_ID"'" },
        "caption": [{ "type": "text", "text": { "content": "Pomodoro" } }]
      }
    }]
  }'

The sandbox, line by line

This table is the reason our widgets are built the way they are. It is worth reading before you design anything for Notion.

A CRM, an OKR tree or a meeting-notes system is not a widget. It is databases with relations between them, rollups that aggregate across those relations, formulas that compute state, and views that filter the result. All of that exists in the Notion API, and all of it can be created headlessly.

The catch is ordering. Since Notion split databases from data sources, a relation property targets a data_source_id, which does not exist until the target database has been created. So a correct install is inherently two passes, and any tool that shows you a single POST /v1/databases per table is not telling you the whole story.

Every widget implements the same four rules. If you are writing your own, copy them. They are what makes a widget configurable from a URL, from a downloaded file, and from an API call without three different code paths.

// the loader every widget ships with
const baked = JSON.parse(
  document.getElementById("bk-config")?.textContent ?? "{}"
);
const qs = new URLSearchParams(location.search);
const cfg = { ...baked };
for (const [k, v] of qs) cfg[k] = v;

const num  = (k, d) => Number.isFinite(+cfg[k]) ? +cfg[k] : d;
const bool = (k, d) => cfg[k] === undefined ? d : ["true","1"].includes(String(cfg[k]));

The failure modes are the useful part. Everything below has been verified against the Notion API reference and the HTML block documentation, not assumed.

You can give Claude Code, Cursor, Windsurf, or Claude Desktop native access to all 203 components via the official MCP server and Agent Skill.