type
status
date
slug
summary
tags
category
icon
url
sync
React Notion X
Fast and accurate React renderer for Notion. TS batteries included. ⚡️
Contents
- Advice
- Features
- Usage
- Styles
- Optional Components
- Private Pages
- Next.js Examples
- Packages
- Supported Blocks
- Performance
- Related
- Contributing
- License
- Sponsor
Advice
If you just want to publish a website using Notion, then we highly recommend using Super.so — a hosted solution with great performance that takes care of all the details for you.
If you want more control over your website via React, then we recommend checking out the accompanying Next.js starter kit, which is free and uses react-notion-x under the hood.
And if you want even more control, then you're in the right place! 👇👇
Features
- 🚀 Simple - TypeScript + React
- ⚡ Fast - 10-100x faster than Notion
- 95-100% Lighthouse scores
- Heavier components can be loaded lazily via next/dynamic
- 💯 Tests - Comes with a comprehensive test suite covering most of Notion's functionality
- 🔥 Solid - Used in production by Potion and thousands of websites
- 💪 Smooth - Supports next/image along with LQIP preview images (demo)
- Framework agnostic - Use with next.js, create-react-app, gatsby, etc
Usage
First, you'll want to fetch the content for a Notion page:
Once you have the data for a Notion page, you can render it via React:
Note: for heavier blocks, you'll have to opt into using them via
NotionRenderer.components. These are not included in the default NotionRenderer export because they're too heavyweight for many use cases.Styles
You'll need to import some CSS styles as well. If you're using Next.js, we recommend you place these imports at the top of
pages/_app.js:Optional Components
The default imports from react-notion-x strive to be as lightweight as possible. Most blocks will render just fine, but some larger blocks like PDFs and collection views (database views) are not included by default.
To use them, you'll need to import the ones you want from
react-notion-x/build/third-party/*:Note that we strongly recommend lazy-loading these components unless you know you'll need them up front for your use case.
If you're using Next.js, you can use
next/dynamic to lazily load them. If your notion content doesn't use one of these heavyweight components, then it won't get loaded into your page. This keeps the initial page bundle small and your website feeling snappy.You'll need to enable them by passing them to the
components prop of NotionRenderer.The
Code component uses Prism under the hood. It comes bundled with support for JavaScript, TypeScript, and CSS by default. To add support for additional language syntaxes, follow the example in components/NotionPage.tsx which lazily loads Prism components at runtime.For
Equation support, you'll need to import the katex CSS styles.For each of these optional components, make sure you're also importing the relevant third-party CSS if needed (above).
Private Pages
You may optionally pass an
authToken and activeUser to the API if you want to access private Notion pages. Both can be retrieved from your web browser. Once you are viewing your workspace, open your Development Tools > Application > Cookies > and Copy the token_v2 and notion_user_id. Respectively, activeUser: notion_user_id, authToken: token_v2.We recommend storing these as environment variables and passing them into the
NotionAPI constructor as follows:Note that this is not the same as the API token provided by the official Notion API since
notion-client uses the unofficial Notion API (which is what all Notion apps use).Next.js Examples
Here's a minimal Next.js example project with the most important code in
pages/[pageId].tsx and components/NotionPage.tsx. You can view this example live on Vercel.Here's a more full-featured Next.js example project with the most important code in
pages/[pageId].tsx and components/NotionPage.tsx. You can view this example live on Vercel.The full-featured demo adds a few nice features:
- Uses
next/imageto serve optimal images
- Uses preview images generated via
lqip-modern
- Lazily bundles larger optional components via
next/dynamic
- Code
- Equation
- Modal
- Collection (e.g., notion databases including table and gallery views)
For a production example, check out the Next.js Notion Starter Kit, which uses react-notion-x under the hood.
Packages
- Package:
react-notion-x- NPM: Environment: Browser + SSR - Description: Fast React renderer for Notion.
- Package:
notion-client- NPM: Environment: Server-side* - Description: Robust TypeScript client for the Notion API.
- Package:
notion-types- NPM: Environment: Universal - Description: Core Notion TypeScript types.
- Package:
notion-utils- NPM: Environment: Universal - Description: Useful utilities for working with Notion data.
- Notion's API should not be called from client-side browsers due to CORS restrictions.
notion-clientis compatible with Node.js and Deno.
Supported Blocks
The majority of Notion blocks and collection views are fully supported.
- Block Type:
Page- Supported: ✅ Yes - Block Type Enum:page- Notes: None
- Block Type:
Text- Supported: ✅ Yes - Block Type Enum:text- Notes: Supports all known text formatting options
- Block Type:
Bookmark- Supported: ✅ Yes - Block Type Enum:bookmark- Notes: Embedded preview of external URL
- Block Type:
Bulleted List- Supported: ✅ Yes - Block Type Enum:bulleted_list- Notes:<ul>
- Block Type:
Numbered List- Supported: ✅ Yes - Block Type Enum:numbered_list- Notes:<ol>
- Block Type:
Heading 1- Supported: ✅ Yes - Block Type Enum:header- Notes:<h1>
- Block Type:
Heading 2- Supported:
- Block Type:
Heading 2- Supported: ✅ Yes - Block Type Enum:sub_header- Notes:<h2>
- Block Type:
Heading 3- Supported: ✅ Yes - Block Type Enum:sub_sub_header- Notes:<h3>
- Block Type:
Quote- Supported: ✅ Yes - Block Type Enum:quote- Notes: None
- Block Type:
Callout- Supported: ✅ Yes - Block Type Enum:callout- Notes: None
- Block Type:
Equation (block)- Supported: ✅ Yes - Block Type Enum:equation- Notes:katexviareact-katex
- Block Type:
Equation (inline)- Supported: ✅ Yes - Block Type Enum:text- Notes:katexviareact-katex
- Block Type:
Todos (checkboxes)- Supported: ✅ Yes - Block Type Enum:to_do- Notes: None
- Block Type:
Table Of Contents- Supported: ✅ Yes - Block Type Enum:table_of_contents- Notes: Seenotion-utilsgetPageTableOfContentshelper function
- Block Type:
Divider- Supported: ✅ Yes - Block Type Enum:divider- Notes: Horizontal line
- Block Type:
Column- Supported: ✅ Yes - Block Type Enum:column- Notes: None
- Block Type:
Column List- Supported: ✅ Yes - Block Type Enum:column_list- Notes: None
- Block Type:
Toggle- Supported: ✅ Yes - Block Type Enum:toggle- Notes:<details>
- Block Type:
Image- Supported: ✅ Yes - Block Type Enum:image- Notes:<img>
- Block Type:
Embed- Supported: ✅ Yes - Block Type Enum:embed- Notes: Generic iframe embeds
- Block Type:
Video- Supported: ✅ Yes - Block Type Enum:video- Notes: iframe
- Block Type:
Figma- Supported: ✅ Yes - Block Type Enum:figma- Notes: iframe
- Block Type:
Google Maps- Supported: ✅ Yes - Block Type Enum:maps- Notes: iframe
- Block Type:
Google Drive- Supported: ✅ Yes - Block Type Enum:drive- Notes: Google Docs, Sheets, etc custom embed
- Block Type:
Tweet- Supported: ✅ Yes - Block Type Enum:tweet- Notes: Uses the twitter embedding SDK
- Block Type:
PDF- Supported: ✅ Yes - Block Type Enum:pdf- Notes: Uses S3 signed URLs andreact-pdf
- Block Type:
Audio- Supported: ✅ Yes - Block Type Enum:audio- Notes: Uses S3 signed URLs and HTML5 audio element
- Block Type:
File- Supported: ✅ Yes - Block Type Enum:file- Notes: Uses S3 signed URLs (generic downloadable file)
- Block Type:
Link- Supported: ✅ Yes - Block Type Enum:text- Notes: External links
- Block Type:
Page Link- Supported: ✅ Yes - Block Type Enum:page- Notes: Link to a notion page in the same workspace
- Block Type:
External Page Link- Supported: ✅ Yes - Block Type Enum:text- Notes: Links to a notion page or collection view in another workspace
- Block Type:
Code (block)- Supported: ✅ Yes - Block Type Enum:code- Notes: Block code syntax highlighting viaprismjs
- Block Type:
Code (inline)- Supported: ✅ Yes - Block Type Enum:text- Notes: Inline code formatting (no syntax highlighting)
- Block Type:
Collections- Supported: ✅ Yes - Block Type Enum: None - Notes: None
- Block Type:
Collection View- Supported: ✅ Yes - Block Type Enum:collection_view- Notes: Collections have a 1:N mapping to collection views
- Block Type:
Collection View Table- Supported: ✅ Yes - Block Type Enum:collection_view- Notes:type = "table"(default table view)
- Block Type:
Collection View Gallery- Supported: ✅ Yes - Block Type Enum:collection_view- Notes:type = "gallery"(grid view)
- Block Type:
Collection View Board- Supported: ✅ Yes - Block Type Enum:collection_view- Notes:type = "board"(kanban view)
- Block Type:
Collection View List- Supported: ✅ Yes - Block Type Enum:collection_view- Notes:type = "list"(vertical list view)
- Block Type:
Collection View Calendar- Supported: ❌ Missing - Block Type Enum:collection_view- Notes:type = "calendar"(embedded calendar view)
- Block Type:
Collection View Page- Supported: ✅ Yes - Block Type Enum:collection_view_page- Notes: 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.
Performance
Google Lighthouse scores for an example page rendered by
react-notion-x on Vercel.Out of the box,
react-notion-x is pretty fast and relatively lightweight, but there are a few key factors to be aware of.Bundlephobia reports a ~27kb gzip bundle size for the main
react-notion-x bundle. This doesn't include the optional third-party components which we recommend lazy loading via next/dynamic only if a page needs them.Another major factor for perf comes from images hosted by Notion. They're generally unoptimized, improperly sized, and not cacheable because Notion has to deal with fine-grained access control that users can change at any time. You can override the default
mapImageUrl function on NotionRenderer to add caching via a CDN like Cloudflare Workers, which is what Notion X does for optimal page load speeds.NotionRenderer also supports lazy image loading with optional low quality image placeholder previews. You can see a demo of this in practice on this page which is using lqip-modern to pre-generate placeholder images that are inspired by Medium.com's image loading.If you're using Next.js, we recommend passing
next/image and next/link to the renderer as follows:This wraps these next.js components in a compatibility layer so
NotionRenderer can use them the same as their non-next.js equivalents <img> and <a>.Related
- Next.js Template - The easiest way to deploy a self-hosted Notion site with Next.js and Vercel. Only takes a few minutes to setup! Uses
react-notion-xunder the hood.
- Notion Test Suite - Comprehensive suite of Notion test pages
react-notion- Original react renderer for notion
react-notion-xstarted as a fork ofreact-notionwith better support for different types of Notion content (especially collections) and grew into something much more comprehensive
react-notionis no longer actively maintained
notion-api-worker- Notion API proxy exposed as a Cloudflare Worker
notion-typesandnotion-clientare a refactored fork ofnotion-api-worker.
- One of the main use cases for
react-notion-xis server-side rendering via Next.js, in which case the CF worker is unnecessary. We recommend that you usenotion-clientinstead.
notion-api-agent- Alternative Notion API client
notion-py- Excellent Python wrapper around the Notion API
Contributing
See the contribution guide and join our amazing list of contributors!
License
MIT © Travis Fischer
This project extends MIT-licensed work by Timo Lins, Tobias Lins, Sam Wight, and other contributors.
Big thanks to Noah Bragg who runs Potion.so for helping to maintain
react-notion-x.Support my OSS work by following me on twitter
Sponsor
Super.so has been kind enough to sponsor this project. If you're looking for a hosted solution that takes a very similar approach to
react-notion-x but handles all of the details for you, then definitely check them out.- 作者:notion2go
- 链接:https://notion2go.com/article/Notion-Client
- 声明:本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明出处。