TypeScript packages for Notion's unofficial API, data types, and related utilities.
- 🚀 Simple - It's all TypeScript. Easy peasy.
- ⚡ Fast - Concurrent network IO for fetching all resources on a page.
- 💯 Tests - Comes with a comprehensive test suite covering 98% of Notion functionality.
- 📓 Docs - Auto-generated docs for all packages.
- 🔥 Solid - Used in production by Notion X (coming soon), Notion VIP, and Notion2Site.
import { NotionAPI } from 'notion-client'
const api = new NotionAPI()
// fetch a notion page's content, including all async blocks, collection queries, and signed urls
const page = await api.getPage('067dd719-a912-471e-a9a3-ac10710e7fdf')
// fetch the data for a specific collection instance
const collectionId = '2d8aec23-8281-4a94-9090-caaf823dd21a'
const collectionViewId = 'ab639a5a-853e-45e1-9ef7-133b486c0acf'
const colectionData = await api.getCollectionData(
collectionId,
collectionViewId
)You can optionally pass an authToken to NotionAPI if you need to access private notion resources.
| Package | NPM | Docs | Environment | Description |
|---|---|---|---|---|
| notion-client | |
docs | Server-side* | Robust TypeScript client for the unofficial Notion API. |
| notion-types |  |
docs | Universal | TypeScript types for core Notion data structures. |
| notion-utils |  |
docs | Universal | Useful utilities for working with Notion data. |
* Notion's API should not be called from client-side browsers due to CORS restrictions. notion-client is compatible with Node.js, Deno, and Cloudflare Workers.
The majority of Notion blocks and collection views are fully supported.
| Block Type | Supported | Block Type | Notes |
|---|---|---|---|
| Page | ✅ Yes | page |
|
| Text | ✅ Yes | text |
Includes all known text formatting options |
| Bookmark | ✅ Yes | bookmark |
Embedded preview of external URL |
| Bulleted List | ✅ Yes | bulleted_list |
<ul> |
| Numbered List | ✅ Yes | numbered_list |
<ol> |
| Heading 1 | ✅ Yes | header |
<h1> |
| Heading 2 | ✅ Yes | sub_header |
<h2> |
| Heading 3 | ✅ Yes | sub_sub_header |
<h3> |
| Quote | ✅ Yes | quote |
|
| Callout | ✅ Yes | callout |
|
| Equation (block) | ✅ Yes | equation |
katex via react-katex |
| Equation (inline) | ✅ Yes | text |
katex via react-katex |
| Todos (checkboxes) | ✅ Yes | to_do |
|
| Table Of Contents | ✅ Yes | table_of_contents |
See notion-utils `get |
| Divider | ✅ Yes | divider |
Horizontal line |
| Column | ✅ Yes | column |
|
| Column List | ✅ Yes | column_list |
|
| Toggle | ✅ Yes | toggle |
<details> |
| Image | ✅ Yes | image |
<img> |
| Embed | ✅ Yes | embed |
Generic iframe embeds |
| Video | ✅ Yes | video |
iframe |
| Figma | ✅ Yes | figma |
iframe |
| Google Maps | ✅ Yes | maps |
iframe |
| Google Drive | ✅ Yes | drive |
Google Docs, Sheets, etc custom embed |
| Tweet | ✅ Yes | tweet |
Uses the twitter embedding SDK |
| ✅ Yes | pdf |
Uses S3 signed URLs and react-pdf | |
| Audio | ✅ Yes | audio |
Uses S3 signed URLs and HTML5 audio element |
| File | ✅ Yes | file |
Uses S3 signed URLs (generic downloadable file) |
| Link | ✅ Yes | text |
External links |
| Page Link | ✅ Yes | page |
Link to a notion page in the same workspace |
| External Page Link | ✅ Yes | text |
Links to a notion page or collection view in another workspace |
| Code (block) | ✅ Yes | code |
Block code syntax highlighting via prismjs |
| Code (inline) | ✅ Yes | text |
Inline code formatting (no syntax highlighting) |
| Collections | ✅ Yes | Also known as databases | |
| Collection View | ✅ Yes | collection_view |
Collections have a 1:N mapping to collection views |
| Collection View Table | ✅ Yes | collection_view |
type = "table" (default table view) |
| Collection View Gallery | ✅ Yes | collection_view |
type = "gallery" (grid view) |
| Collection View Board | ✅ Yes | collection_view |
type = "board" (kanban view) |
| Collection View List | ✅ Yes | collection_view |
type = "list" (vertical list view) |
| Collection View Calendar | ❌ Missing | collection_view |
type = "calendar" (embedded calendar view) |
| Collection View Page | ✅ Yes | collection_view_page |
Collection view as a standalone page |
Please let us know if you find any issues or missing blocks.
All known blocks and most known configuration settings can be found in our test suite.
- Notion Test Suite - Comprehensive suite of Notion test pages
- Includes all individual blocks
- Includes all collection views
- Covers most formatting options
- More edge cases and feature coverage will be added over time
- react-notion - React renderer for Notion data.
- notion-api-worker - Notion API proxy exposed as a Cloudflare Worker.
- This provided a solid starting point for
notion-typesandnotion-client. - Currently doesn't handle collection data very robustly.
- One of the main use cases for
react-notionis server-side rendering via Next.js, in which case the CF worker is unnecessary.
- This provided a solid starting point for
- notion-api-agent - Alternative Notion API client.
MIT © Travis Fischer
Support my OSS work by following me on twitter
This project extends MIT-licensed work by Timo Lins, Tobias Lins, Sam Wight, and other contributors.
