@gendive/react-notion-renderer 사용 가이드
이 문서는 @gendive/react-notion-renderer@0.1.1 기준으로 작성되었습니다.
- Notion 페이지 / 데이터베이스를 어떻게 렌더링하는지
- 어떤 레이아웃과 옵션(cardOptions, queryOptions) 이 있는지
- 이번에 추가된 보드 카드 레이아웃 옵션과 페이지네이션, embed 블록 사용법
을 한 번에 정리합니다.
1. 기본 개념
1-1. 주요 컴포넌트
NotionPageRenderer/NotionPageModal- Notion 페이지(block list)를 렌더링
NotionPageModal은 모달 안에서 페이지 상세를 보여줄 때 사용
NotionDatabaseRenderer- normalize된 데이터베이스 데이터(
NotionDatabaseData)를 다양한 레이아웃으로 렌더링
- normalize된 데이터베이스 데이터(
NotionThemeProvider- 라이트/다크 등 테마 제공
1-2. 데이터 가져오기 (서버)
라이브러리가 제공하는 서버 유틸을 사용해서 페이지/데이터베이스 데이터를 가져옵니다.
import { fetchNotionPage, fetchNotionDatabase } from '@gendive/react-notion-renderer';
const page = await fetchNotionPage(pageId, process.env.NOTION_TOKEN!);
const database = await fetchNotionDatabase(databaseId, process.env.NOTION_TOKEN!, queryOptions);
2. 페이지 렌더링
2-1. 기본 렌더링
import { NotionThemeProvider, NotionPage } from '@gendive/react-notion-renderer';
export default async function Page() {
const page = await fetchNotionPage(
process.env.NOTION_PAGE_ID!,
process.env.NOTION_TOKEN!,
);
return (
<NotionThemeProvider>
<NotionPage page={page} />
</NotionThemeProvider>
);
}
2-2. 모달로 페이지 상세 보기
"use client";
import { useState } from 'react';
import { NotionPageModal } from '@gendive/react-notion-renderer';
import { fetchNotionPageClient } from '@gendive/react-notion-renderer/client';
export function PageModalExample() {
const [pageId, setPageId] = useState<string | null>(null);
return (
<>
<button type="button" onClick={() => setPageId('notion-page-id')}>열기</button>
<NotionPageModal
pageId={pageId}
onClose={() => setPageId(null)}
fetchPage={fetchNotionPageClient}
/>
</>
);
}
3. 데이터베이스 렌더링
3-1. 레이아웃 종류
NotionDatabaseRenderer / NotionDatabaseById에서 사용 가능한 레이아웃:
layout="table"- 테이블 형태
layout="board-card"- 카드 그리드 형태 (보드)
layout="list"- 썸네일이 있는 리스트 형태 (블로그 포스트 스타일)
3-2. 서버 컴포넌트에서 직접 렌더링
import {
fetchNotionDatabase,
NotionDatabaseRenderer,
} from '@gendive/react-notion-renderer';
export default async function DatabasePage() {
const database = await fetchNotionDatabase(
process.env.NOTION_DATABASE_ID!,
process.env.NOTION_TOKEN!,
);
return (
<NotionDatabaseRenderer database={database} layout="board-card" />
);
}
4. 보드 카드 레이아웃 (board-card)
보드 카드 레이아웃은 cardOptions로 강하게 커스터마이징할 수 있습니다.
4-1. 기본 사용
<NotionDatabaseRenderer
database={database}
layout="board-card"
/>
4-2. 카드 정보/테마 커스터마이징
<NotionDatabaseRenderer
database={database}
layout="board-card"
cardOptions={{
titleProperty: '프로젝트명',
descriptionProperty: '설명',
badgeProperties: ['상태', '우선순위'],
showCover: true,
cardTheme: {
cardBackground: '#020617',
cardBorderColor: '#1f2937',
cardRadius: 12,
titleColor: '#e5e7eb',
descriptionColor: '#9ca3af',
},
}}
/>
4-3. 그리드 레이아웃 & 페이지네이션 (0.1.1+)
버전 0.1.1부터 보드 카드 그리드 옵션과 페이지네이션을 지원합니다.
<NotionDatabaseRenderer
database={database}
layout="board-card"
cardOptions={{
showCover: true,
// 레이아웃 옵션
fullWidth: true, // 컨테이너 좌우 꽉 차게
columns: 4, // 한 줄에 4개 카드
// 페이지네이션
pagination: {
enabled: true,
pageSize: 12,
style: {
activeBackground: '#2563eb',
activeColor: '#ffffff',
buttonRadius: 999,
},
},
}}
/>
주요 옵션 요약
columns?: number(기본: 3)- 보드 카드 레이아웃에서 한 줄에 표시할 카드 개수
fullWidth?: boolean(기본: true)true: 부모 컨테이너 폭 기준으로 균등 분할 (1fr)false:cardWidth기준 고정 폭 카드 그리드
cardWidth?: number(기본: 280)fullWidth = false일 때 카드 가로 폭(px)
pagination?: NotionPaginationOptionsenabled?: boolean(기본: false)pageSize?: number(기본: 12)style?: NotionPaginationStyle
type NotionPaginationStyle = {
buttonBackground?: string;
buttonColor?: string;
buttonRadius?: number;
activeBackground?: string;
activeColor?: string;
buttonPadding?: string;
fontSize?: string;
};
type NotionPaginationOptions = {
enabled?: boolean;
pageSize?: number;
style?: NotionPaginationStyle;
};
5. 리스트 레이아웃 (list)
5-1. 기본 사용
<NotionDatabaseRenderer
database={database}
layout="list"
/>
5-2. 썸네일 위치/스타일 조정
<NotionDatabaseRenderer
database={database}
layout="list"
cardOptions={{
showCover: true,
thumbnailPosition: 'right', // 'left' 또는 'right'
cardTheme: {
cardBackground: '#ffffff',
cardBorderColor: '#e5e7eb',
cardRadius: 12,
},
listStyle: {
thumbnailWidth: 180,
thumbnailHeight: 100,
contentPadding: 20,
gap: 20,
titleSize: '1.25rem',
},
}}
/>
6. 필터링 & 정렬 (queryOptions)
fetchNotionDatabase / NotionDatabaseById에서 queryOptions로 Notion API 필터/정렬을 그대로 사용할 수 있습니다.
<NotionDatabaseById
databaseId={databaseId}
layout="board-card"
queryOptions={{
filters: [
{
property: '상태',
type: 'status',
condition: 'equals',
value: '진행중',
},
],
sorts: [
{
property: '우선순위',
direction: 'ascending',
},
],
}}
/>
타입 정의는 README의 NotionDatabaseQueryOptions 섹션을 참고하세요.
7. Embed 블록
7-1. 무엇을 지원하나요?
- Notion의
embed블록 타입을 normalize 하여 내부NotionEmbedBlock으로 변환 NotionPageRenderer에서 iframe으로 렌더링convertToEmbedUrl을 사용해 YouTube/Vimeo 링크는 자동으로 embed URL로 변환
7-2. 렌더링 형태
- 기본 높이: 1200px
- caption이 있다면 iframe 아래에 작은 글씨로 표시
(사용자는 별도 설정 없이 Notion에서 embed 블록만 추가하면 됩니다.)
8. 카드 클릭 시 페이지 상세 모달
NotionDatabaseRenderer + NotionPageModal 조합으로, 보드/리스트에서 카드를 클릭했을 때 Notion 페이지 상세를 모달로 띄울 수 있습니다.
"use client";
import { useState } from 'react';
import {
NotionDatabaseRenderer,
NotionPageModal,
type NotionDatabaseData,
} from '@gendive/react-notion-renderer';
import { fetchNotionPageClient } from '@gendive/react-notion-renderer/client';
export function DatabaseWithModal({ database }: { database: NotionDatabaseData }) {
const [selectedPageId, setSelectedPageId] = useState<string | null>(null);
return (
<>
<NotionDatabaseRenderer
database={database}
layout="board-card"
cardOptions={{
showCover: true,
fullWidth: true,
columns: 3,
pagination: {
enabled: true,
pageSize: 12,
},
}}
onRowClick={(pageId) => setSelectedPageId(pageId)}
/>
<NotionPageModal
pageId={selectedPageId}
onClose={() => setSelectedPageId(null)}
fetchPage={fetchNotionPageClient}
/>
</>
);
}
9. 어디서 더 볼 수 있나요?
- README.md
- 설치 / 기본 예제 / API 레퍼런스
- USAGE_EXAMPLES.md
- 필터/정렬, 리스트/보드 예시, 서버 컴포넌트 예시 등 코드 중심 예제 모음
- demo/
- Next.js 기반 실제 동작 데모 (보드 카드 뷰 + 모달 등)
이 문서는 개념과 옵션 위주로 정리되어 있으니, 실제 코드 패턴은 USAGE_EXAMPLES.md와 demo 폴더를 함께 보는 것을 추천합니다.