Skip to content
Notion Arena

Documentation

Read this before you install

Other component libraries document how to use their components. This one documents the platform they run on, because Notion's constraints, not our design choices, decide what is possible. Everything here is verified against the Notion API reference or the HTML block documentation, and every limit is cited.
An open manual surrounded by the tools it documents: a wrench, angle brackets, a database cylinder and a shield.

The short version

Notion has no plugin system, so there is no single install path. There are three, and they have almost nothing in common:

  • Embed URL: we host the widget, Notion iframes it. Zero setup, works on Free, picks up our updates, and dies if we do.
  • HTML block: you upload the same file to Notion's own storage. Offline forever, frozen at the version you took, and sandboxed hard enough that it cannot read the page it sits on.
  • Native recipe: we call the Notion API to build real databases, relations, rollups, formulas and views. Data-driven and shared, and it needs an integration token plus four manual click-paths the API cannot cover.
The one rule that explains the catalog
A widget cannot read your Notion data. If a component needs to show numbers from your workspace, it is a recipe, not because we preferred it that way, but because the HTML block sandbox has no network access and no bridge to its parent page.

What is in the box

203 components: 192 widgets and 11 native recipes. 192 are free, including their HTML downloads.

📦

The HTML block sandbox

What Notion's native HTML block can and cannot do, verified line by line. Read this before you design anything for it.

Open
📐

Notion API limits, cited

Block nesting, children per request, rate limits, the missing button type, automations, recurring templates, and the two-pass data-source problem.

Open
🛠️

Authoring a widget

The configuration contract, the theming contract, the persistence contract, and how to add a component to the catalog.

Open
🧬

Authoring a recipe

Declaring databases, views, seed rows and page bodies; how relations resolve; when to write a manual step instead.

Open
🧭

How it works

The three delivery channels side by side, with the failure table and a decision matrix.

Open
📇

The registry

Endpoints, the item schema, and three ways to consume the catalog from code or from an agent.

Open

For AI agents & coding assistants

Notion Arena publishes an official MCP server and Agent Skill so Claude Code, Cursor, Windsurf, or Claude Desktop can discover, configure, and install components directly:

  • Claude Code MCP: claude mcp add --scope project notion-arena -- npx -y notion-arena-mcp
  • Standalone MCP runner: npx -y notion-arena-mcp@0.2.2
  • Agent Skill (skills.sh): npx skills add SynergyFlowLabs/notion-arena --skill notion-arena

Conventions used in these docs

  • Notion-Version: 2026-03-11 is the version every request in this project sends. It is the version that introduced HTML blocks via the File Upload API, heading_4, tab blocks, and the position field that replaced after.
  • A manual step in a recipe is never a shortcut we took. Each one names the API limitation that forces it.
  • Capability claims are booleans in the catalog, interactive, offlineSafe, persistsLocally, writesToNotion, needsNetwork, and they are exposed in the registry so an agent can filter on them instead of reading prose.