DOCSEARCHbyAlgolia
Submit Docs

react-notion-x

repository·master·Indexed 26 days ago

https://github.com/notionx/react-notion-x

A fast and accurate React renderer for Notion pages. The ecosystem includes react-notion-x for rendering, notion-client for fetching data via an unofficial API, notion-x-to-md for converting pages to GitHub-Flavored Markdown (GFM), and utility packages like notion-types and notion-utils. It supports a wide range of Notion block types, including collections, equations, and embeds, with optional heavyweight components to minimize bundle size.

Tokens
18.3K
Snippets
38
Records
108
Agent score
90%

What's inside react-notion-x

  2. Fetch a database's content with getPage

    master

    When passing a database ID to the getPage method, the response object contains block, collection, and collection_view properties.

    The block property is a map where keys are block IDs and values contain metadata (role, value). The order of IDs in the block map follows this pattern:

    1. The collection view ID
    2. The parent page ID containing the database
    3. IDs of all child pages inside the database
    4. All child blocks of each page

    Block types can include header, text, list, media, page, or collection_view.

  3. Optimize Image Loading and Caching

    master

    Notion-hosted images are often unoptimized and not cacheable. To improve performance, you can:

    1. Override mapImageUrl: On the NotionRenderer, override the mapImageUrl function to route images through a CDN (like Cloudflare Workers) for caching.
    2. Lazy Loading: NotionRenderer supports lazy image loading with optional low-quality image placeholder (LQIP) previews.
    3. Next.js Integration: Use the nextImage component prop as described in the Next.js integration guide to leverage Next.js image optimization.

  4. Optimize Performance with Next.js Components

    master

    If you are using Next.js, you can improve performance and SEO by passing next/image (or next/legacy/image) and next/link to the NotionRenderer via the components prop. This wraps the Next.js components in a compatibility layer so they can be used in place of standard <img> and <a> tags.

    Note: Custom image components are currently only enabled with preview images or by setting forceCustomImages to true on the NotionRenderer.

    import Image from 'next/image' // or import Image from 'next/legacy/image' if you use legacy Image
import Link from 'next/link'

export default ({ recordMap }) => (
  <NotionRenderer
    recordMap={recordMap}
    components={{
      nextImage: Image, // or nextLegacyImage: LegacyImage,
      nextLink: Link
    }}
  />
)

  5. Important notes for using notion-x-to-md

    master

    Authentication

    No Notion API keys or integrations are required. Ensure your Notion page is set to publicly accessible.

    Image URLs

    Images hosted by Notion are temporary and will eventually become inaccessible. To ensure permanent image URLs, you should post-process the ExtendedRecordMap returned by NotionAPI.getPage to upload images to a permanent storage and map the block IDs to the new URLs.

    Feature Support

    • Markdown Format: Outputs GitHub-Flavored Markdown (GFM).
    • Collections (Databases): Supported. All database views are rendered as Markdown tables. Includes support for number, date, expression, and formula formatting.
    • Tweet Embeds: Uses tweet-to-md. Polls are not shown. GIF and video tweets only show the poster image.
    • Embeds: Videos are shown as links. Iframe embeds (e.g., Maps, Figma, Drive) render as empty.

  10. Use optional heavyweight components

    master

    To keep the initial bundle small, heavyweight blocks like Code, Collection, Equation, Modal, and Pdf are not included in the default NotionRenderer export.

    To use them:

    1. Import the component from react-notion-x/third-party/* (ideally using next/dynamic for lazy loading).
    2. Pass the component to the components prop of NotionRenderer.

    Available third-party components:

    • Code
    • Collection
    • Equation
    • Modal
    • Pdf
    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 }
)

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

  12. Import required CSS styles

    master

    To ensure correct rendering, you must import the core react-notion-x styles. Depending on your features, you may also need to import styles for code syntax highlighting (Prism) or equations (KaTeX).

    Required:

    • react-notion-x/styles.css

    Optional:

    • prismjs/themes/prism-tomorrow.css (for Code blocks)
    • katex/dist/katex.min.css (for Equations)
    // 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'