# @udus/notion-renderer

> ![Notion Renderer](/assets/logo.png)

Latest version **1.0.0-alpha.83** (published 2023-12-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install @udus/notion-renderer
pnpm add @udus/notion-renderer
yarn add @udus/notion-renderer
bun add @udus/notion-renderer
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0-alpha.83 |
| Published | 2023-12-29 |
| First published | 2023-10-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 7 |
| Unpacked size | 3 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | udus |
| Keywords | notion, react, notion-api |

## Links

- npm: https://www.npmjs.com/package/@udus/notion-renderer
- Repository: https://github.com/udus122/notion-renderer
- Homepage: https://github.com/udus122/notion-renderer#readme
- Issues: https://github.com/udus122/notion-renderer/issues
- npm.io page: https://npm.io/package/@udus/notion-renderer

## Dependencies (7)

- [dotenv](https://npm.io/package/dotenv.md) ^16.3.1
- [date-fns](https://npm.io/package/date-fns.md) ^2.30.0
- [date-fns-tz](https://npm.io/package/date-fns-tz.md) ^2.0.0
- [@notionhq/client](https://npm.io/package/@notionhq/client.md) ^2.2.14
- [modern-normalize](https://npm.io/package/modern-normalize.md) ^2.0.0
- [@extractus/oembed-extractor](https://npm.io/package/@extractus/oembed-extractor.md) ^4.0.1
- [@extractus/article-extractor](https://npm.io/package/@extractus/article-extractor.md) ^8.0.4

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.0.0-alpha.83 (latest) — 2023-12-29
- 1.0.0-alpha.86 (alpha) — 2023-12-30
- 1.0.0-alpha.85 — 2023-12-30
- 1.0.0-alpha.84 — 2023-12-29
- 1.0.0-alpha.82 — 2023-12-29
- 1.0.0-alpha.81 — 2023-12-29
- 1.0.0-alpha.80 — 2023-12-29
- 1.0.0-alpha.79 — 2023-12-29
- 1.0.0-alpha.78 — 2023-12-29
- 1.0.0-alpha.77 — 2023-12-29
- 1.0.0-alpha.76 — 2023-12-29
- 1.0.0-alpha.75 — 2023-12-29
- 1.0.0-alpha.74 — 2023-12-29
- 1.0.0-alpha.73 — 2023-12-29
- 1.0.0-alpha.72 — 2023-12-27
- … 44 more at https://npm.io/package/@udus/notion-renderer/versions

## README

![Notion Renderer](/assets/logo.png)

# Notion Renderer
![npm version](https://img.shields.io/npm/v/%40udus%2Fnotion-renderer) ![GitHub License](https://img.shields.io/github/license/udus122/notion-renderer) ![GitHub Repo stars](https://img.shields.io/github/stars/udus122/notion-renderer?style=social)


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

```bash
npm install @udus/notion-renderer@alpha
```

## Usage

### Quick Start

First, fetch the blocks of the page you want to render using [`fetchBlockList`](https://github.com/udus122/notion-renderer/blob/alpha/src/libs/notion/blocks/blocks.ts#L104).  
Next, pass the fetched block list to the [`BlockRenderer`](https://github.com/udus122/notion-renderer/blob/alpha/src/components/Blocks/Renderer.tsx#L24).

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

```typescript
import { BlockRenderer } from "@udus/notion-components/components";
import { fetchBlockList } from "@udus/notion-components/libs";

import type { InferGetStaticPropsType, NextPage } from "next";

export const getStaticProps = async () => {
  const blocks = await fetchBlockList("YOUR_PAGE_ID");

  return {
    props: {
      blocks,
    },
  };
};

type Props = InferGetStaticPropsType<typeof getStaticProps>;

const Index: NextPage<Props> = ({ blocks }) => {
  return <BlockRenderer blocks={blocks} />;
};

export default Index;
```

And you will need to import CSS styles like below.  
```typescript
// Load the CSS to be used with the Notion Renderer.
import "@udus/notion-components/styles/globals.css";
// Load the CSS used for rendering equations
import "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

```typescript
export default () => (
  <BlockRenderer
    blocks={blocks}
    blockMapper={
      toggle: OpenedToggle,
      heading_1: OpenedHeading1,
      heading_2: OpenedHeading2,
      heading_3: OpenedHeading3,
    } />
)
```

#### Color

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

```typescript
export default () => (
  <BlockRenderer blocks={blocks} theme="dark" />
)
```

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.

```css
:root {
  /* light-theme */
  --color-text-default: rgb(55 53 47);
  --color-bg-default: rgb(255 255 255);
  --color-pill-default: rgb(227 226 224 / 50%);
  --color-text-gray: rgb(120 119 116);
  --color-bg-gray: rgb(241 241 239);
  --color-pill-gray: rgb(227 226 224);
  --color-text-brown: rgb(159 107 83);
  --color-bg-brown: rgb(244 238 238);
  --color-pill-brown: rgb(238 224 218);
  --color-text-orange: rgb(217 115 13);
  --color-bg-orange: rgb(251 236 221);
  --color-pill-orange: rgb(250 222 201);
  --color-text-yellow: rgb(203 145 47);
  --color-bg-yellow: rgb(251 243 219);
  --color-pill-yellow: rgb(253 236 200);
  --color-text-green: rgb(68 131 97);
  --color-bg-green: rgb(237 243 236);
  --color-pill-green: rgb(219 237 219);
  --color-text-blue: rgb(51 126 169);
  --color-bg-blue: rgb(231 243 248);
  --color-pill-blue: rgb(211 229 239);
  --color-text-purple: rgb(144 101 176);
  --color-bg-purple: #eae4f2;
  --color-pill-purple: rgb(244 240 247 / 80%);
  --color-text-pink: rgb(193 76 138);
  --color-bg-pink: rgb(249 238 243 / 80%);
  --color-pill-pink: rgb(245 224 233);
  --color-text-red: rgb(212 76 71);
  --color-bg-red: rgb(253 235 236);
  --color-pill-red: rgb(255 226 221);

  /* dark-theme */
  .notion-dark {
    --color-text-default: rgb(255 255 255 / 81%);
    --color-bg-default: rgb(25 25 25);
    --color-pill-default: rgb(55 55 55);
    --color-text-gray: rgb(155 155 155);
    --color-bg-gray: rgb(47 47 47);
    --color-pill-gray: rgb(90 90 90);
    --color-text-brown: rgb(186 133 111);
    --color-bg-brown: rgb(74 50 40);
    --color-pill-brown: rgb(96 59 44);
    --color-text-orange: rgb(199 125 72);
    --color-bg-orange: rgb(92 59 35);
    --color-pill-orange: rgb(133 76 29);
    --color-text-yellow: rgb(202 152 73);
    --color-bg-yellow: rgb(86 67 40);
    --color-pill-yellow: rgb(137 99 42);
    --color-text-green: rgb(82 158 114);
    --color-bg-green: rgb(36 61 48);
    --color-pill-green: rgb(43 89 63);
    --color-text-blue: rgb(94 135 201);
    --color-bg-blue: rgb(20 58 78);
    --color-pill-blue: rgb(40 69 108);
    --color-text-purple: rgb(157 104 211);
    --color-bg-purple: rgb(60 45 73);
    --color-pill-purple: rgb(73 47 100);
    --color-text-pink: rgb(209 87 150);
    --color-bg-pink: rgb(78 44 60);
    --color-pill-pink: rgb(105 49 76);
    --color-text-red: rgb(223 84 82);
    --color-bg-red: rgb(82 46 42);
    --color-pill-red: rgb(110 54 48);
  }
    }
```

## Supported Objects

### [Block](https://developers.notion.com/reference/block)

Most common block types are supported.

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

#### [Rich text](https://developers.notion.com/reference/rich-text#rich-text-type-objects)

| Rich text Type                                                         | Supported | Mapper Field Name | HTML Tag                    | Notes                                                                       |
| ---------------------------------------------------------------------- | --------- | ----------------- | --------------------------- | --------------------------------------------------------------------------- |
| [Equation](https://developers.notion.com/reference/rich-text#equation) | ✅         | `equation`        | [katex](https://katex.org/) | In order to render properly, you need to import `katex/dist/katex.min.css`. |
| [Mention](https://developers.notion.com/reference/rich-text#mention)   | ✅         | `mention`         | `<span>`                    |                                                                             |
| [Text](https://developers.notion.com/reference/rich-text#text)         | ✅         | `text`            | `<span>`                    |                                                                             |


##### [Annotation](https://developers.notion.com/reference/rich-text#the-annotation-object)

| 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](https://developers.notion.com/reference/page-property-values#checkbox)                 | ✅         | `checkbox`         |       |
| [Created by](https://developers.notion.com/reference/page-property-values#created-by)             | ✅         | `created_by`       |       |
| [Created time](https://developers.notion.com/reference/page-property-values#created-time)         | ✅         | `created_time`     |       |
| [Date](https://developers.notion.com/reference/page-property-values#date)                         | ✅         | `date`             |       |
| [Email](https://developers.notion.com/reference/page-property-values#email)                       | ✅         | `email`            |       |
| [Files](https://developers.notion.com/reference/page-property-values#files)                       | ✅         | `files`            |       |
| [Formula](https://developers.notion.com/reference/page-property-values#formula)                   | ✅         | `formula`          |       |
| [Last edited by](https://developers.notion.com/reference/page-property-values#last-edited-by)     | ✅         | `last_edited_by`   |       |
| [Last edited time](https://developers.notion.com/reference/page-property-values#last-edited-time) | ✅         | `last_edited_time` |       |
| [Multi-select](https://developers.notion.com/reference/page-property-values#multi-select)         | ✅         | `multi_select`     |       |
| [Number](https://developers.notion.com/reference/page-property-values#number)                     | ✅         | `number`           |       |
| [People](https://developers.notion.com/reference/page-property-values#people)                     | ✅         | `people`           |       |
| [Phone number](https://developers.notion.com/reference/page-property-values#phone-number)         | ✅         | `phone_number`     |       |
| [Relation](https://developers.notion.com/reference/page-property-values#relation)                 | ✅         | `relation`         | WIP   |
| [Rollup](https://developers.notion.com/reference/page-property-values#rollup)                     | ✅         | `rollup`           | WIP   |
| [Rich text](https://developers.notion.com/reference/page-property-values#rich-text)               | ✅         | `rich_text`        |       |
| [Select](https://developers.notion.com/reference/page-property-values#select)                     | ✅         | `select`           |       |
| [Status](https://developers.notion.com/reference/page-property-values#status)                     | ✅         | `status`           |       |
| [Title](https://developers.notion.com/reference/page-property-values#title)                       | ✅         | `title`            |       |
| [URL](https://developers.notion.com/reference/page-property-values#url)                           | ✅         | `url`              |       |
| [Unique ID](https://developers.notion.com/reference/page-property-values#unique-id)               | ✅         | `unique_id`        |       |
| [Verification](https://developers.notion.com/reference/page-property-values#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](https://choosealicense.com/licenses/mit/)

---
_Source: https://npm.io/package/@udus/notion-renderer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._