React Notion X

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

Contents

• React Notion X
• Contents
• Advice
• Features
• Usage
• Styles
• Optional Components
  • Custom Button Components
• Custom Button Components
• Private Pages
• Next.js Examples
• Packages
• Supported Blocks
• Performance
• Related
• Contributing
• License

Advice

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 tens of thousands of websites
• 💪 Smooth - Supports next/image along with LQIP preview images (demo)
• Framework agnostic - Use with next.js, vite, remix, 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 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/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/third-party/*:

import { Code } from 'react-notion-x/third-party/code'
import { Collection } from 'react-notion-x/third-party/collection'
import { Equation } from 'react-notion-x/third-party/equation'
import { Modal } from 'react-notion-x/third-party/modal'
import { Pdf } from 'react-notion-x/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/third-party/code').then((m) => m.Code)
)
const Collection = dynamic(() =>
  import('react-notion-x/third-party/collection').then((m) => m.Collection)
)
const Equation = dynamic(() =>
  import('react-notion-x/third-party/equation').then((m) => m.Equation)
)
const Pdf = dynamic(
  () => import('react-notion-x/third-party/pdf').then((m) => m.Pdf),
  {
    ssr: false
  }
)
const Modal = dynamic(
  () => import('react-notion-x/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. You will likely want to add prismjs to your project as a dependency when using the Code component so TypeScript doesn't complain.

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).

Custom Button Components

Button blocks are rendered by default using a simple built-in implementation that displays the button text with proper colors. For advanced functionality like handling button clicks with automations (opening URLs, triggering webhooks), you can provide a custom Button component:

import { NotionButton } from './components/NotionButton'

export default ({ recordMap }) => (
  <NotionRenderer
    recordMap={recordMap}
    components={{
      Button: NotionButton
    }}
  />
)

Custom Button Components

Button blocks are now built-in by default with full automation support including:

• Opening external URLs in new tabs
• Internal page navigation
• Sending webhooks with Notion-format payloads
• Custom header support

The default Button component is exported from react-notion-x and handles most common use cases automatically. If you need custom behavior, you can override it:

import { Button } from 'react-notion-x'

// Optional: Create a custom button component
const MyCustomButton = ({ blockId, block, className }) => {
  // Your custom implementation
  return <Button blockId={blockId} block={block} className={className} />
}

export default ({ recordMap }) => (
  <NotionRenderer
    recordMap={recordMap}
    components={{
      Button: MyCustomButton
    }}
  />
)

For webhook functionality, you'll need a server-side proxy endpoint to avoid CORS issues. See examples/minimal/pages/api/webhook-proxy.ts for a Next.js implementation.

The Button component receives blockId, block, and optional className as props. See packages/react-notion-x/src/components/button.tsx for the default implementation.

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

Package	NPM	Environment	Description
react-notion-x		Browser + SSR	Fast React renderer for Notion.
notion-client		Server-side*	Robust TypeScript client for the Notion API.
notion-types		Universal	Core Notion TypeScript types.
notion-utils		Universal	Useful utilities for working with Notion data.
notion-compat		Server-side	Compatibility layer between the official Notion API and unofficial private API.
notion-x-to-md		Universal	Converts a Notion page to Markdown. Very useful for LLMs.

* Notion's API should not be called from client-side browsers due to CORS restrictions. notion-client is compatible with Node.js, Bun, Deno, CF workers, etc.

Supported Blocks

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

Block Type	Supported	Block Type Enum	Notes
Page	✅ Yes	page
Text	✅ Yes	text	Supports 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>