npm package: @gendive/react-notion-renderer
Description: Notion 페이지/데이터베이스를 React에서 렌더링하는 라이브러리
Latest version: 0.1.3

# @gendive/react-notion-renderer

[한국어](./README.ko.md) | **English**

A React library for rendering Notion pages and databases as beautiful dashboards.

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![npm version](https://img.shields.io/npm/v/@gendive/react-notion-renderer.svg)](https://www.npmjs.com/package/@gendive/react-notion-renderer)

📚 **[Documentation](https://gendata-dev.github.io/gendive-react-notion-renderer/)**

![Screenshot](./assets/screenshot.png)

---

## Why we built this

While building [DevDive](https://www.devdive.ai), we wanted to **use Notion as a dashboard**. We needed to manage content in Notion and display it as beautiful card views or tables on our website.

Existing libraries didn't quite fit:
- Relied on unofficial APIs
- Hard to customize styles
- Couldn't render databases as cards/boards

So we built our own. A library that **uses only the official Notion API**, **is easy to customize**, and **renders databases like dashboards**.

> This library is built by the [Gendive](https://github.com/gendata-dev) team.
> We also run **[DevDive](https://www.devdive.ai)**, a platform to easily combine and use AI models. Check it out! 🙏

---

## ⭐ Give us a Star!

If this library helped you, please **star this repo on GitHub**!

Your star means a lot to us:
- Motivates us to build more features
- Helps other developers discover this library
- Contributes to the open source ecosystem

---

## Features

### Page Rendering
- ✅ Notion API integration (`fetchNotionPage`)
- ✅ Multiple block types (paragraph, heading, quote, code, callout, divider, list)
- ✅ Rich text styling (bold, italic, underline, strikethrough, code, link, color)
- ✅ Theme system (light/dark mode)

### Database Rendering
- ✅ Notion API integration (`fetchNotionDatabase`)
- ✅ Multiple property types (title, rich_text, select, multi_select, status, number, date, checkbox, files, last_edited_time)
- ✅ 3 layout options
  - **Table**: Traditional table view
  - **Board Card**: Card grid view (with cover images)
  - **List**: List view (with thumbnails)

### Advanced Features
- ✅ **Column selection**: Control visible columns with `visibleColumns` / `hiddenColumns`
- ✅ **Filtering**: Notion API filter support (status, select, checkbox, number, date, text, etc.)
- ✅ **Sorting**: Single/multi-column sorting
- ✅ **Theme customization**: Fine-grained control over colors, spacing, shadows
- ✅ **Click events**: `onRowClick` for card click handling
- ✅ **Modal component**: `NotionPageModal` for displaying page details

## Installation

```bash
npm install @gendive/react-notion-renderer
```

## Quick Start

### 1. Environment Variables

```env
NOTION_TOKEN=secret_xxx...
NOTION_PAGE_ID=xxx...
NOTION_DATABASE_ID=xxx...
```

### 2. Page Rendering

```tsx
import { NotionThemeProvider } from '@gendive/react-notion-renderer';
import NotionPageById from '@/components/NotionPageById';

export default function Page() {
  return (
    <NotionThemeProvider>
      <NotionPageById pageId={process.env.NOTION_PAGE_ID!} />
    </NotionThemeProvider>
  );
}
```

### 3. Database Rendering

#### Table View
```tsx
<NotionDatabaseById
  databaseId={databaseId}
  layout="table"
  visibleColumns={['Title', 'Status', 'Date']}
/>
```

#### Board Card View
```tsx
<NotionDatabaseById
  databaseId={databaseId}
  layout="board-card"
  cardOptions={{
    showCover: true,
    fullWidth: true,
    columns: 3,
    pagination: {
      enabled: true,
      pageSize: 12,
    },
    cardTheme: {
      cardBackground: '#020617',
      cardBorderColor: '#1f2937',
      titleColor: '#e5e7eb',
    },
  }}
/>
```

#### List View
```tsx
<NotionDatabaseById
  databaseId={databaseId}
  layout="list"
  cardOptions={{
    showCover: true,
    thumbnailPosition: 'right',
    cardTheme: {
      cardBackground: '#ffffff',
      cardBorderColor: '#e5e7eb',
      cardRadius: 12,
    },
    listStyle: {
      thumbnailWidth: 180,
      thumbnailHeight: 100,
      contentPadding: 20,
      gap: 20,
      titleSize: '1.25rem',
    },
  }}
/>
```

### 4. Page Detail Modal

> **Important**: Notion API cannot be called directly from the browser (CORS). Use the API Route provided by the library.

**1. Create API Route** (`app/api/notion/page/[pageId]/route.ts`)
```tsx
export { GET } from '@gendive/react-notion-renderer/api';
```

**2. Client Component**
```tsx
"use client";

import { useState } from 'react';
import {
    NotionDatabaseRenderer,
    NotionPageModal
} from '@gendive/react-notion-renderer';
import { fetchNotionPageClient } from '@gendive/react-notion-renderer/client';

export default function DatabaseWithModal({ database }) {
    const [selectedPageId, setSelectedPageId] = useState(null);

    return (
        <>
            <NotionDatabaseRenderer
                database={database}
                layout="board-card"
                onRowClick={(pageId) => setSelectedPageId(pageId)}
            />

            <NotionPageModal
                pageId={selectedPageId}
                onClose={() => setSelectedPageId(null)}
                fetchPage={fetchNotionPageClient}
            />
        </>
    );
}
```

### 5. Filtering and Sorting

```tsx
<NotionDatabaseById
  databaseId={databaseId}
  layout="board-card"
  queryOptions={{
    filters: [
      {
        property: 'Status',
        type: 'status',
        condition: 'equals',
        value: 'In Progress',
      },
    ],
    sorts: [
      {
        property: 'Priority',
        direction: 'ascending',
      },
    ],
  }}
/>
```

## API Reference

See [Documentation](https://gendata-dev.github.io/gendive-react-notion-renderer/) for full API reference.

## License

MIT License © 2025 [Gendive](https://github.com/gendata-dev)

The Gendive team has decided to release this repository under the MIT license to contribute to the open source community.

We would like to express our gratitude to all the Gendive team members and developers who made this possible. Thank you! 💙

Free to use, modify, and distribute. See [LICENSE](./LICENSE) for details.