@notionhq/custom-blocks
v0.5.1
Published
> [!NOTE] **Pre-release.** Custom blocks are in alpha. Breaking changes may land at any time.
Maintainers
Keywords
Readme
@notionhq/custom-blocks
[!NOTE] Pre-release. Custom blocks are in alpha. Breaking changes may land at any time.
Custom blocks let you build custom UI inside Notion that uses workspace data. This SDK provides APIs to read and update data the viewer can access. It includes framework-neutral TypeScript APIs and React hooks.
Install
Create a worker project with ntn workers new --template custom. Use the dependencies and
entrypoint that the Notion CLI generates.
React is optional. Blocks that import @notionhq/custom-blocks/react need react and react-dom.
For local preview, run ntn workers customblocks dev from the worker project. Open the shell URL
printed by the command. Install
@notionhq/custom-blocks-dev-shell
as a devDependency to pin the shell and get its reference docs in node_modules. See
docs/deployment.md for local serving details.
Quick start
Declare your custom block along with the rest of your worker definition:
// src/index.ts
import { Worker } from "@notionhq/workers"
const worker = new Worker()
export default worker
worker.customBlock("hello", {
path: "./blocks/hello",
command: "npx vite build",
})Wrap your React app in <NotionCustomBlock> at the block's entry point:
// blocks/hello/src/index.tsx
import "@notionhq/custom-blocks/nds.css"
import { NotionCustomBlock, NotionTokenScope } from "@notionhq/custom-blocks/react"
import { createRoot } from "react-dom/client"
import { App } from "./App"
import "./style.css"
const root = document.getElementById("root")
if (!root) throw new Error("The root element is missing.")
createRoot(root).render(
<NotionCustomBlock>
<NotionTokenScope>
<App />
</NotionTokenScope>
</NotionCustomBlock>,
)Hooks can then read live content directly from Notion:
// blocks/hello/src/App.tsx
import { useBlockId } from "@notionhq/custom-blocks/react"
export function App() {
const blockId = useBlockId()
return <div className="app">Hello from {blockId}.</div>
}Save these styles in blocks/hello/src/style.css:
.app {
color: var(--content-primary);
background: var(--bg-base);
padding: var(--spacing-12);
border: 1px solid var(--border-primary);
border-radius: var(--radius-12);
}<NotionCustomBlock> connects the SDK to the host and waits for host state before rendering its
children. It reports the initial content height so the host can size the iframe before displaying
it. It also reports later height changes automatically.
Notion design tokens
The optional @notionhq/custom-blocks/nds.css stylesheet provides Notion CSS variables for matching
Notion's UI. These variables cover colors, spacing, typography, and borders. Import the stylesheet
once. Place components that use the variables inside <NotionTokenScope>, as shown above.
<NotionTokenScope> keeps Notion CSS variables in sync with the host’s theme and contrast settings.
NotionTokenScopeProps has one required children prop.
CSS variables apply only within <NotionTokenScope>. Place portal containers inside that scope, or
wrap the portal content in another <NotionTokenScope>.
Outside React, use customBlock.getTheme() and customBlock.getContrastMode() to read the current
appearance, or customBlock.subscribeToTheme() and customBlock.subscribeToContrastMode() to
follow changes. See Block location and appearance for details.
Reference
Each page covers one API category. Import framework-neutral APIs from @notionhq/custom-blocks.
Import React hooks and components from @notionhq/custom-blocks/react.
docs/lifecycle.md—<NotionCustomBlock>,useCustomBlockInit,initCustomBlock,NotInIframeError. The handshake, the React wrapper, sizing.docs/block-location.md—useBlockId,useParent,usePage,useTheme,useContrastMode,NotionTokenScope, andNotionTokenScopeProps. Where the block sits and how to read the host's appearance.docs/data-sources.md—dataSources.query / getPage / create,customBlock.subscribeToDataSource,useDataSource,useManifest,customBlock.getManifest, the row, property, and date-value types, plus a worked example.docs/pages.md—pages.create / get / openand page instance mutations, parent variants (including the recommendeddata_source_key), property input shapes.docs/links.md—links.open, URL validation, host-owned confirmation, and external-navigation errors.docs/users.md—users.list / get, theNotionUsershape, paging.docs/errors.md— request results, error format, error codes, retries, and initialization failures.docs/grants.md— the block manifest'sgrants, viewer approval, and the reservednot_grantedcode.docs/bridge-interceptors.md—registerMessageInterceptorandMessageInterceptorfor controlled bridge responses.docs/deployment.md— worker-backed deploys, localhost self-hosted fallback, where the manifest comes from.
Limitations
Custom blocks do not render on pages published with Notion Sites.
Custom blocks run in sandboxed iframes. A block cannot navigate the top-level page, call
window.open, or start an authentication redirect. Use pages.open to navigate to Notion pages and
links.open for host-approved HTTP and HTTPS URLs.
By default, a block cannot request external origins. A workspace owner can allow specific HTTPS
origins under Settings → Notion AI → Workers → Manage → Custom block external network access. To
allow subdomains, add a wildcard origin such as https://*.example.com. Add https://example.com
separately if the block also needs the base domain. The allowlist applies to every custom block in
the workspace. For fetch or XMLHttpRequest, an external API must allow the block's origin
through CORS.
When a custom block makes repeated requests to an external API, consider its rate limits. Consider batching requests or caching results to reduce unnecessary calls. If the API returns 429, follow its retry guidance.
Never put API secrets in a block bundle. Store them in the Worker. Read more in the custom block security guide.
Bridge protocol
The SDK communicates with Notion through a versioned postMessage protocol. Use the SDK's public
APIs and exported types. Do not send bridge messages directly.
