npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@notionhq/custom-blocks

v0.5.1

Published

> [!NOTE] **Pre-release.** Custom blocks are in alpha. Breaking changes may land at any time.

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, and NotionTokenScopeProps. 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 / open and page instance mutations, parent variants (including the recommended data_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, the NotionUser shape, paging.
  • docs/errors.md — request results, error format, error codes, retries, and initialization failures.
  • docs/grants.md — the block manifest's grants, viewer approval, and the reserved not_granted code.
  • docs/bridge-interceptors.md — registerMessageInterceptor and MessageInterceptor for 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.