Notion Renderer

A fully customizable React renderer for the official Notion API.

[!NOTE] Please note that this package is currently in alpha release.
Therefore, there may be significant changes to the API without prior notice.

Example

• Storybook: https://udus122.github.io/notion-renderer/?path=/docs/renderer--docs

Installation

1npm install @udus/notion-renderer@alpha

Usage

Quick Start

First, fetch the blocks of the page you want to render using fetchBlockList.
Next, pass the fetched block list to the BlockRenderer.

If you are using Next.js, you can do it as shown in the sample code below.

1import { BlockRenderer } from "@udus/notion-components/components";
2import { fetchBlockList } from "@udus/notion-components/libs";
3
4import type { InferGetStaticPropsType, NextPage } from "next";
5
6export const getStaticProps = async () => {
7  const blocks = await fetchBlockList("YOUR_PAGE_ID");
8
9  return {
10    props: {
11      blocks,
12    },
13  };
14};
15
16type Props = InferGetStaticPropsType<typeof getStaticProps>;
17
18const Index: NextPage<Props> = ({ blocks }) => {
19  return <BlockRenderer blocks={blocks} />;
20};
21
22export default Index;

And you will need to import CSS styles like below.

1// Load the CSS to be used with the Notion Renderer.
2import "@udus/notion-components/styles/globals.css";
3// Load the CSS used for rendering equations
4import "katex/dist/katex.min.css";

Please set your Notion integration token as an environment variable named NOTION_TOKEN.

.env
NOTION_TOKEN=secret_epO17gyx***********************************

Custom Component

You can render the page using a custom component instead of the default components, you can also create and use your own components. Please see the example of creating custom components at the following link: https://github.com/udus122/notion-renderer/tree/alpha/src/components/Blocks/Custom

1export default () => (
2  <BlockRenderer
3    blocks={blocks}
4    blockMapper={
5      toggle: OpenedToggle,
6      heading_1: OpenedHeading1,
7      heading_2: OpenedHeading2,
8      heading_3: OpenedHeading3,
9    } />
10)

Color

If you want to use dark mode, please set the theme to theme="dark" as follows.(theme="light" is default.)

1export default () => (
2  <BlockRenderer blocks={blocks} theme="dark" />
3)

If you want to change the color theme, please overwrite the CSS variables set to .notion-light or .notion-dark as follows. The default values are listed below.

1:root {
2  /* light-theme */
3  --color-text-default: rgb(55 53 47);
4  --color-bg-default: rgb(255 255 255);
5  --color-pill-default: rgb(227 226 224 / 50%);
6  --color-text-gray: rgb(120 119 116);
7  --color-bg-gray: rgb(241 241 239);
8  --color-pill-gray: rgb(227 226 224);
9  --color-text-brown: rgb(159 107 83);
10  --color-bg-brown: rgb(244 238 238);
11  --color-pill-brown: rgb(238 224 218);
12  --color-text-orange: rgb(217 115 13);
13  --color-bg-orange: rgb(251 236 221);
14  --color-pill-orange: rgb(250 222 201);
15  --color-text-yellow: rgb(203 145 47);
16  --color-bg-yellow: rgb(251 243 219);
17  --color-pill-yellow: rgb(253 236 200);
18  --color-text-green: rgb(68 131 97);
19  --color-bg-green: rgb(237 243 236);
20  --color-pill-green: rgb(219 237 219);
21  --color-text-blue: rgb(51 126 169);
22  --color-bg-blue: rgb(231 243 248);
23  --color-pill-blue: rgb(211 229 239);
24  --color-text-purple: rgb(144 101 176);
25  --color-bg-purple: #eae4f2;
26  --color-pill-purple: rgb(244 240 247 / 80%);
27  --color-text-pink: rgb(193 76 138);
28  --color-bg-pink: rgb(249 238 243 / 80%);
29  --color-pill-pink: rgb(245 224 233);
30  --color-text-red: rgb(212 76 71);
31  --color-bg-red: rgb(253 235 236);
32  --color-pill-red: rgb(255 226 221);
33
34  /* dark-theme */
35  .notion-dark {
36    --color-text-default: rgb(255 255 255 / 81%);
37    --color-bg-default: rgb(25 25 25);
38    --color-pill-default: rgb(55 55 55);
39    --color-text-gray: rgb(155 155 155);
40    --color-bg-gray: rgb(47 47 47);
41    --color-pill-gray: rgb(90 90 90);
42    --color-text-brown: rgb(186 133 111);
43    --color-bg-brown: rgb(74 50 40);
44    --color-pill-brown: rgb(96 59 44);
45    --color-text-orange: rgb(199 125 72);
46    --color-bg-orange: rgb(92 59 35);
47    --color-pill-orange: rgb(133 76 29);
48    --color-text-yellow: rgb(202 152 73);
49    --color-bg-yellow: rgb(86 67 40);
50    --color-pill-yellow: rgb(137 99 42);
51    --color-text-green: rgb(82 158 114);
52    --color-bg-green: rgb(36 61 48);
53    --color-pill-green: rgb(43 89 63);
54    --color-text-blue: rgb(94 135 201);
55    --color-bg-blue: rgb(20 58 78);
56    --color-pill-blue: rgb(40 69 108);
57    --color-text-purple: rgb(157 104 211);
58    --color-bg-purple: rgb(60 45 73);
59    --color-pill-purple: rgb(73 47 100);
60    --color-text-pink: rgb(209 87 150);
61    --color-bg-pink: rgb(78 44 60);
62    --color-pill-pink: rgb(105 49 76);
63    --color-text-red: rgb(223 84 82);
64    --color-bg-red: rgb(82 46 42);
65    --color-pill-red: rgb(110 54 48);
66  }
67    }

Supported Objects

Block

Most common block types are supported.

Block Type	Supported	Mapper Field Name	HTML Tag	Notes
Audio	✅	audio	<audio>
Bookmark	✅	bookmark	<div>	When retrieving an object from the API, we use @extractus/article-extractor to obtain meta information of the site such as OGP images and descriptions.
Breadcrumb	✅	breadcrumb	<div>	When retrieving an object from the API, we recursively obtain the parent page.
Bulleted list item	✅	bullted_list/bullted_list_item	<ul>/<li>
Callout	✅	callout	<div>
Child database	✅	child_database	<Link>
Child page	✅	child_page	<Link>
Code	✅	code	<pre><code>	By default, SyntaxHighlight is not included. If necessary, please create a custom component.
Column list and column	✅	column_list	<div>
Divider	✅	divider	<hr>
Embed	✅	embed	passing the oEmbed content to dangerouslySetInnerHTML	When retrieving an object from the API, we use @extractus/oembed-extractor to obtain the oEmbed content.
Equation	✅	equation	katex	In order to render properly, you need to import katex/dist/katex.min.css.
File	✅	file	<Link>
Heading1	✅	heading_1	<h1>
Heading2	✅	heading_2	<h2>
Heading3	✅	heading_3	<h3>
Image	✅	image	<img>
Link Preview	✅	link_preview	<Link>	When retrieving an object from the API, we use @extractus/article-extractor to obtain meta information of the site such as OGP images and descriptions.
Link To Page	✅	link_to_page	<Link>
Numbered lit item	✅	numbered_list/numbered_list_item	<ol>/<li>
Paragraph	✅	paragraph	<p>
PDF	✅	pdf	<object type="application/pdf>
Quote	✅	quote	<blockquote>
Synced block	✅	synced_block	<div>
Table	✅	table	<table>
Table of contents	✅	table_of_contents	<div>
Template	❌	template		Deprecated
To do	✅	to_do	<div>
Toggle Blocks	✅	toggle	<details><summary>
Video	✅	video	<video>	YouTube is supported through the oEmbed API.

Rich text

Rich text Type	Supported	Mapper Field Name	HTML Tag	Notes
Equation	✅	equation	katex	In order to render properly, you need to import katex/dist/katex.min.css.
Mention	✅	mention	<span>
Text	✅	text	<span>

Annotation

Annotation Type	Supported	Mapper Field Name	HTML Tag	Notes
Bold	✅	bold	<strong>
Italic	✅	italic	<em>
Strikethrough	✅	strikethrough	<del>
Underline	✅	underline	<u>
Code	✅	code	<code>
Color	✅	color	<span>

Page

Page components	Supported	Notes
Cover	✅
Icon	✅
Title	✅

Properties

Property Type	Supported	Mapper Field Name	Notes
Checkbox	✅	checkbox
Created by	✅	created_by
Created time	✅	created_time
Date	✅	date
Email	✅	email
Files	✅	files
Formula	✅	formula
Last edited by	✅	last_edited_by
Last edited time	✅	last_edited_time
Multi-select	✅	multi_select
Number	✅	number
People	✅	people
Phone number	✅	phone_number
Relation	✅	relation	WIP
Rollup	✅	rollup	WIP
Rich text	✅	rich_text
Select	✅	select
Status	✅	status
Title	✅	title
URL	✅	url
Unique ID	✅	unique_id
Verification	❌	verification

Database

Layout Type	Supported	Layout Name	Notes
Table	✅	table
Gallery	✅	gallery
List	✅	list
Board	❌	board
Calendar	❌	calendar
Timeline	❌	timeline

Contributing

Pull requests are welcome.

License

MIT