Custom blocks quickstart

Custom blocks are in private alpha:

Do not discuss publicly or share with anyone outside your workspace.
Access must be enabled per workspace. Installing the SDK does not grant access.
These APIs may experience breaking changes without notice.

This guide takes you from nothing to a custom block rendering in a Notion page, then adds Notion data to it.

Prerequisites

Node.js 22 or later.
The ntn CLI. See installation.
A workspace enabled for the custom blocks alpha.

Update the ntn CLI

ntn update

Older ntn versions lack support for custom blocks. Run ntn --version to confirm version 0.21.2 or later.

ntn login

This connects ntn to a workspace and stores credentials in your OS keychain. Run ntn whoami to confirm.

Scaffold a new Worker

ntn workers new my-example-worker --template custom
cd my-example-worker
npm install

The custom template is the smallest Worker template containing a custom block and its required dependencies, and it works without any data source setup.Other starting points are available with --template:

Template	What it renders
`custom`	Minimal, with no data sources
`habit-tracker`	A month-at-a-glance habit tracker with streaks
`org-chart`	A tree org chart from a People data source
`whiteboard`	A collaborative whiteboard canvas with sticky notes and arrows

Understand the two parts

Custom block code has two parts, each with its own SDK. At deploy time, ntn reads the Worker declaration to build and publish the block. The frontend runs in the browser whenever someone views the Notion page.src/index.ts is the Worker, written with @notionhq/workers. It declares the block, which includes information about building its frontend code and which data sources it expects:

src/index.ts

import { Worker } from "@notionhq/workers"

const worker = new Worker()
export default worker

// The block key. Any stable name you choose. The template uses "custom".
worker.customBlock("custom", {
	// Where to find the block's frontend source code. This can be any arbitrary
	// path within the Worker's directory.
	path: "./blocks/custom",

	// How to build the source code.
	command: "npx vite build",

	// Where to output the built files.
	output: "dist",

	// Data source schemas expected by the block's source code. These can be
	// bound to arbitrary Notion data sources.
	dataSources: {},
})

blocks/custom/src/index.tsx is the block’s frontend code, written with @notionhq/custom-blocks. Wrap UI code in NotionCustomBlock, which performs the handshake with the Notion host, and NotionTokenScope, which makes Notion’s design tokens available so the block matches the surrounding page:

blocks/custom/src/index.tsx

import "@notionhq/custom-blocks/nds.css"
import {
	NotionCustomBlock,
	NotionTokenScope,
} from "@notionhq/custom-blocks/react"
import ReactDOM from "react-dom/client"

function App() {
	return <h1>Hello world</h1>
}

const root = document.getElementById("root")
if (!root) throw new Error("Missing #root element")

ReactDOM.createRoot(root).render(
	<NotionCustomBlock>
		<NotionTokenScope>
			<App />
		</NotionTokenScope>
	</NotionCustomBlock>,
)

The built-in templates use React. NotionCustomBlock automatically resizes React blocks to fit their content, but any frontend works. For a framework-neutral frontend, initCustomBlock() runs the same handshake and resolves with the block’s context. See initialization and appearance and sizing.

Preview locally (optional)

Before you deploy, run the block against a local mock of the Notion host:

ntn workers customblocks dev

The dev shell runs on localhost. For blocks that declare data sources, connect sample sources and map their properties before the block renders.See previewing before deploy for usage instructions, including how to test against sample data.

Deploy the Worker

A custom block ships with its Worker, so there is no separate custom block deploy step:

ntn workers deploy

This builds the block’s source using the declared command, uploads the contents of output, and publishes it with the Worker.

Share the Worker (optional)

Share with workspace members from the Developer portal. With at least Can connect access, members can find the block’s registered slash command in the / menu and insert it on any page they can edit. See sharing workers for more.

Insert a custom block into a page

On desktop or web, type /custom on a page you can edit and choose your block.If the block declares data sources, Notion asks you to bind each one to a real data source before it renders. The custom template declares none, so it renders immediately.

Add Notion data

A block never names a data source. It declares the shape of the data it needs, and whoever inserts the block binds that declaration to something real — which is what keeps a block reusable across workspaces. Binding a block to Notion data explains the full model. In the Worker code, declare data sources on the capability:

src/index.ts

import { Worker } from "@notionhq/workers"

const worker = new Worker()
export default worker

worker.customBlock("custom", {
	path: "./blocks/custom",
	command: "npx vite build",
	output: "dist",
	dataSources: {
		issues: {
			name: "Issues",
			description: "The team's issues",
			properties: {
				title: { name: "Title", type: "title" },
				status: { name: "Status", type: "status" },
			},
		},
	},
})

Replace the earlier App component with this component. Keep the imports, root creation, and provider wrappers from that example.

import { useDataSource } from "@notionhq/custom-blocks/react"

function App() {
	const { items, isLoading, hasMore, error } = useDataSource("issues", {
		limit: 100,
		filter: { key: "title", title: { is_not_empty: true } },
		sorts: [{ key: "title", direction: "ascending" }],
	})

	if (error) return <p role="alert">Could not load issues: {error.message}</p>
	if (isLoading) return <p>Loading issues…</p>
	if (items.length === 0) return <p>No matching issues.</p>

	return (
		<div>
			<ul>
				{items.map((item) => {
					const title = item.propertiesByKey.title
					return <li key={item.id}>{typeof title === "string" ? title : "Untitled"}</li>
				})}
			</ul>
			{hasMore && <p>More issues match this query. These results are incomplete.</p>}
		</div>
	)
}

The keys you declare in the Worker are the keys the frontend queries by, so keep them in sync. Deploy again and Notion will ask you to bind issues the next time the block is configured — until it is bound, the block will not render, so declare only what the block genuinely needs.

Add a block to an existing Worker

You do not need a fresh project. A custom block is a Worker capability, so it can live in a Worker you already have alongside its syncs, tools, and webhooks. Add the custom blocks SDK to the existing package.json in the Worker’s root directory. Run this command from that directory:

npm install @notionhq/custom-blocks

Then register the block in src/index.ts with worker.customBlock, pointing path at that directory. If your assets are already built and there is no build step to run, declare a static source instead. See the Worker capability reference for every option.

Next steps

Read Notion data

Query rows and update them from the block.

Write to Notion

Create, update, and archive pages from the block.

Handle errors

Understand the error contract and what is retryable.

Worker capability

Every option on worker.customBlock().

Get started

Guides

Workers SDK reference

Custom blocks SDK reference

CLI reference

Custom blocks quickstart

Prerequisites

Add Notion data

Add a block to an existing Worker

Next steps

Read Notion data

Write to Notion

Handle errors

Worker capability

​Prerequisites

​Add Notion data

​Add a block to an existing Worker

​Next steps

Read Notion data

Write to Notion

Handle errors

Worker capability

Prerequisites

Add Notion data

Add a block to an existing Worker

Next steps