@gendive/react-notion-renderer

한국어 | English

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

📚 Documentation

Why we built this

While building DevDive, 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 team. We also run DevDive, 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

npm install @gendive/react-notion-renderer

Quick Start

1. Environment Variables

NOTION_TOKEN=secret_xxx...
NOTION_PAGE_ID=xxx...
NOTION_DATABASE_ID=xxx...

2. Page Rendering

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

<NotionDatabaseById
  databaseId={databaseId}
  layout="table"
  visibleColumns={['Title', 'Status', 'Date']}
/>

Board Card View

<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

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

export { GET } from '@gendive/react-notion-renderer/api';

2. Client Component

"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

<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 for full API reference.

License

MIT License © 2025 Gendive

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 for details.