Custom blocks

Custom blocks are user-authored interfaces that Notion renders inside pages. They run in sandboxed iframes with access to live Notion data. Use one when you need a block or view that Notion does not provide: a chart over a data source, an org chart, a whiteboard canvas, a scheduling grid.

​

How the pieces fit together

A custom block is a worker capability. You declare it on a worker the same way you declare a sync or a tool, so everything a worker gives you — secrets, syncs, tools — is available in the same project. See how workers work. A custom block requires two pieces of code:

• In the worker, src/index.ts declares the custom block capability using @notionhq/workers: where the block’s source lives, how to build it, and which data sources it expects. ntn reads this at deploy time.
• In the block’s own directory, an ordinary web app renders the UI and talks to its Notion host through @notionhq/custom-blocks. This runs in the browser, on every page view.

A custom block is deployed as part of a worker. ntn workers deploy builds the frontend, uploads it, and publishes it with the worker. There is no separate custom block deploy step. After deployment, you can insert the block on any page by typing /custom or its registered slash command. Sharing a worker makes its custom blocks available to workspace members. See sharing workers to share the worker from the Developer portal and choose an access level.

​

Get started

​

Guides

​

Workers SDK reference

​

Custom blocks SDK reference

​

CLI reference