Project Icon

react-notion-x

高性能React渲染器 助力Notion内容展示

react-notion-x是专为Notion设计的高性能React渲染器。该项目支持TypeScript,渲染速度比Notion原生快10-100倍,Lighthouse评分达95-100。它具备全面测试覆盖,支持next/image和LQIP预览图像,已在Potion等数千网站中应用。react-notion-x可与Next.js、create-react-app和Gatsby等框架集成,为开发者提供简单高效的Notion内容渲染方案。

React Notion X

React Notion X

Fast and accurate React renderer for Notion. TS batteries included. ⚡️

NPM Build Status Prettier Code Formatting NPM

Contents

Advice

If you just want to publish a website using Notion, then we highly recommend using Super.so — a hosted solution with great perf 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:

import { NotionAPI } from 'notion-client'

const notion = new NotionAPI()

const recordMap = await notion.getPage('067dd719a912471ea9a3ac10710e7fdf')

Once you have the data for a Notion page, you can render it via React:

import * as React from 'react'
import { NotionRenderer } from 'react-notion-x'

export default ({ recordMap }) => (
  <NotionRenderer recordMap={recordMap} fullPage={true} darkMode={false} />
)

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:

// core styles shared by all of react-notion-x (required)
import 'react-notion-x/src/styles.css'

// used for code syntax highlighting (optional)
import 'prismjs/themes/prism-tomorrow.css'

// used for rendering equations (optional)
import 'katex/dist/katex.min.css'

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/*:

import { Code } from 'react-notion-x/build/third-party/code'
import { Collection } from 'react-notion-x/build/third-party/collection'
import { Equation } from 'react-notion-x/build/third-party/equation'
import { Modal } from 'react-notion-x/build/third-party/modal'
import { Pdf } from 'react-notion-x/build/third-party/pdf'

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.

import dynamic from 'next/dynamic'

const Code = dynamic(() =>
  import('react-notion-x/build/third-party/code').then((m) => m.Code)
)
const Collection = dynamic(() =>
  import('react-notion-x/build/third-party/collection').then(
    (m) => m.Collection
  )
)
const Equation = dynamic(() =>
  import('react-notion-x/build/third-party/equation').then((m) => m.Equation)
)
const Pdf = dynamic(
  () => import('react-notion-x/build/third-party/pdf').then((m) => m.Pdf),
  {
    ssr: false
  }
)
const Modal = dynamic(
  () => import('react-notion-x/build/third-party/modal').then((m) => m.Modal),
  {
    ssr: false
  }
)

You'll need to enable them by passing them to the components prop of NotionRenderer.

export default ({ recordMap }) => (
  <NotionRenderer
    recordMap={recordMap}
    components={{
      Code,
      Collection,
      Equation,
      Modal,
      Pdf
    }}
  />
)

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 workpace, open your Development Tools > Application > Cookie > 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:

const notion = new NotionAPI({
  activeUser: process.env.NOTION_ACTIVE_USER,
  authToken: process.env.NOTION_TOKEN_V2
})

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/image to serve optimal images
  • Uses preview images generated via lqip-modern
  • Lazily bundles larger optional components via next/dynamic
    • Code
    • Equation
    • Pdf
    • 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

PackageNPMEnvironmentDescription
react-notion-xNPMBrowser + SSRFast React renderer for Notion.
notion-clientNPMServer-side*Robust TypeScript client for the Notion API.
notion-typesNPMUniversalCore Notion TypeScript types.
notion-utilsNPMUniversalUseful 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 and Deno.

Supported Blocks

The majority of Notion blocks and collection views are fully supported.

Block TypeSupportedBlock Type EnumNotes
Page✅ Yespage
Text✅ YestextSupports all known text formatting options
Bookmark✅ YesbookmarkEmbedded preview of external URL
Bulleted List✅ Yesbulleted_list<ul>
Numbered List✅ Yesnumbered_list<ol>
Heading 1✅ Yesheader<h1>
Heading 2✅ Yessub_header<h2>
Heading 3✅ Yessub_sub_header<h3>
Quote✅ Yesquote
Callout✅ Yescallout
Equation (block)✅ Yesequationkatex via react-katex
Equation (inline)✅ Yestextkatex via react-katex
Todos (checkboxes)✅ Yesto_do
Table Of Contents✅ Yestable_of_contentsSee notion-utils getPageTableOfContents helper funtion
Divider✅ YesdividerHorizontal line
Column✅ Yescolumn
Column List✅ Yescolumn_list
Toggle✅ Yestoggle<details>
Image✅ Yesimage<img>
Embed✅ YesembedGeneric iframe embeds
Video✅ Yesvideoiframe
Figma✅ Yesfigmaiframe
Google Maps✅ Yesmapsiframe
Google Drive✅ YesdriveGoogle Docs, Sheets, etc custom embed
Tweet✅ YestweetUses the twitter embedding SDK
PDF✅ YespdfUses S3 signed URLs and react-pdf
Audio✅ YesaudioUses S3 signed URLs and HTML5 audio element
File✅ YesfileUses S3 signed URLs (generic downloadable file)
Link✅ YestextExternal links
Page Link✅ YespageLink to a notion page in the same workspace
External Page Link✅ YestextLinks to a notion page or collection view in another workspace
Code (block)✅ YescodeBlock code syntax highlighting via prismjs
Code (inline)✅ YestextInline code formatting (no syntax highlighting)
Collections✅ YesAlso known as databases
Collection View✅ Yescollection_viewCollections have a 1:N mapping to collection views
Collection View Table✅ Yescollection_viewtype = "table" (default table view)
Collection View Gallery✅ Yescollection_viewtype = "gallery" (grid view)
Collection View Board✅ Yescollection_viewtype = "board" (kanban view)
Collection View List✅ Yescollection_viewtype = "list" (vertical list view)
Collection View Calendar❌ Missingcollection_viewtype = "calendar" (embedded calendar view)
Collection View Page✅ Yescollection_view_pageCollection 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
Google Lighthouse scores for an example page rendered by `react-notion-x` on Vercel.

Bundlephobia

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

项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手,通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能,支持100+编程语言,与主流编辑器无缝集成,显著提升开发效率和代码质量。

Project Cover

问小白

问小白是一个基于 DeepSeek R1 模型的智能对话平台,专为用户提供高效、贴心的对话体验。实时在线,支持深度思考和联网搜索。免费不限次数,帮用户写作、创作、分析和规划,各种任务随时完成!

Project Cover

白日梦AI

白日梦AI提供专注于AI视频生成的多样化功能,包括文生视频、动态画面和形象生成等,帮助用户快速上手,创造专业级内容。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案,通过智能技术简化视频制作流程。无论是企业宣传还是个人分享,有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

讯飞绘镜

讯飞绘镜是一个支持从创意到完整视频创作的智能平台,用户可以快速生成视频素材并创作独特的音乐视频和故事。平台提供多样化的主题和精选作品,帮助用户探索创意灵感。

Project Cover

讯飞文书

讯飞文书依托讯飞星火大模型,为文书写作者提供从素材筹备到稿件撰写及审稿的全程支持。通过录音智记和以稿写稿等功能,满足事务性工作的高频需求,帮助撰稿人节省精力,提高效率,优化工作与生活。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术,为商家提供一键生成商品图和营销文案的服务,显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台,让商品第一时间被种草。

Project Cover

Trae

Trae是一种自适应的集成开发环境(IDE),通过自动化和多元协作改变开发流程。利用Trae,团队能够更快速、精确地编写和部署代码,从而提高编程效率和项目交付速度。Trae具备上下文感知和代码自动完成功能,是提升开发效率的理想工具。

Project Cover

AIWritePaper论文写作

AIWritePaper论文写作是一站式AI论文写作辅助工具,简化了选题、文献检索至论文撰写的整个过程。通过简单设定,平台可快速生成高质量论文大纲和全文,配合图表、参考文献等一应俱全,同时提供开题报告和答辩PPT等增值服务,保障数据安全,有效提升写作效率和论文质量。

投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号