> ## Documentation Index
> Fetch the complete documentation index at: https://developers.notion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom blocks

> Build custom interfaces directly inside Notion with access to live Notion data.

<Warning>
  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.
</Warning>

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](/workers/get-started/overview#how-it-works).

**A custom block requires two pieces of code:**

* **In the worker**, `src/index.ts` declares the custom block capability using [`@notionhq/workers`](/workers/reference/sdk): 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`](/custom-blocks/sdk/initialization). This runs in the browser, on every page view.

**A custom block is deployed as part of a worker.** [`ntn workers deploy`](/custom-blocks/cli/commands) 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](/workers/guides/sharing-workers) to share the worker from the Developer portal and choose an access level.

## Get started

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/custom-blocks/quickstart">
    Scaffold a block, preview it locally, deploy it, and give it Notion data.
  </Card>

  <Card title="Binding to Notion data" icon="database" href="/custom-blocks/guides/data-sources">
    How a block declares the data it needs and gets bound to a real data source.
  </Card>
</CardGroup>

## Guides

| Page | Covers |
| - | - |
| [Quickstart](/custom-blocks/quickstart) | Scaffold a custom block, preview it locally, and deploy it into a Notion page. |
| [How a block initializes](/custom-blocks/guides/lifecycle) | The handshake with the host, live context, and what fails at boot. |
| [Binding to Notion data](/custom-blocks/guides/data-sources) | How a declared data source gets bound to real Notion data. |
| [Previewing before deploy](/custom-blocks/guides/preview) | Running a block against the local dev shell. |
| [Security](/custom-blocks/guides/security) | The isolation model and a block author's responsibilities. |

## Workers SDK reference

| Page | Covers |
| - | - |
| [Worker capability](/custom-blocks/workers/capability) | Reference for new `worker.customBlock()` capability. |

## Custom blocks SDK reference

| Page | Covers |
| - | - |
| [Initialization](/custom-blocks/sdk/initialization) | `NotionCustomBlock`, `initCustomBlock`, and loading states. |
| [App context](/custom-blocks/sdk/app-context) | Block ID, parent, page, current user, and manifest. |
| [Appearance and sizing](/custom-blocks/sdk/appearance) | Design tokens, theme, contrast mode, and auto-resize. |
| [Data sources](/custom-blocks/sdk/data-sources) | Querying rows and updating them. |
| [Pages](/custom-blocks/sdk/pages) | Creating, reading, updating, and archiving pages. |
| [Users](/custom-blocks/sdk/users) | Reading the current user and listing workspace users. |
| [Error handling](/custom-blocks/sdk/errors) | The error contract and how to handle failures. |

## CLI reference

| Page | Covers |
| - | - |
| [ntn CLI commands for custom blocks](/custom-blocks/cli/commands) | `ntn workers customblocks` and the related worker commands. |