Skip to main content

데이터베이스 - 리스트 & 테이블 레이아웃

Notion 데이터베이스를 리스트 또는 테이블 형태로 렌더링하는 방법을 알아봅니다.

실제 동작 데모​

리스트 뷰 (썸네일 오른쪽)​

리스트 뷰 (썸네일 왼쪽)​

테이블 뷰​

테이블 뷰 (특정 컬럼만)​

tip

위 데모는 실제 동작하는 컴포넌트입니다. 전체 Storybook에서 더 많은 옵션을 테스트해보세요.

테이블 레이아웃​

엑셀처럼 행/열로 데이터를 보여줍니다.

언제 쓰나요?​

  • 여러 프로퍼티를 한눈에 비교하고 싶을 때
  • 정렬/검색이 필요한 데이터 목록
  • 관리자 페이지, 대시보드

완성 코드​

// app/tasks/page.tsx

import { NotionDatabaseById } from '@gendive/react-notion-renderer';

export default function TasksPage() {
  return (
    <NotionDatabaseById
      databaseId="2baa76221f4080f8ac12ed40f6885c72"
      token={process.env.NOTION_TOKEN!}
      layout="table"
    />
  );
}

특정 컬럼만 보여주기​

모든 컬럼이 아니라 일부만 보여주고 싶다면:

<NotionDatabaseById
  databaseId="..."
  token="..."
  layout="table"
  visibleColumns={['이름', '상태', '마감일']}  // 이 컬럼만 표시
/>

특정 컬럼 숨기기​

반대로 일부 컬럼만 숨기고 싶다면:

<NotionDatabaseById
  databaseId="..."
  token="..."
  layout="table"
  hiddenColumns={['내부메모', '담당자ID']}  // 이 컬럼은 숨김
/>
tip

visibleColumns와 hiddenColumns를 둘 다 쓰면 visibleColumns가 우선합니다.

리스트 레이아웃​

블로그 글 목록처럼 세로로 나열되는 형태입니다.

언제 쓰나요?​

  • 블로그 포스트 목록
  • 뉴스/공지사항 피드
  • 제목 + 설명 + 썸네일 조합

완성 코드​

// app/blog/page.tsx

import { NotionDatabaseById } from '@gendive/react-notion-renderer';

export default function BlogPage() {
  return (
    <NotionDatabaseById
      databaseId="2baa76221f4080f8ac12ed40f6885c72"
      token={process.env.NOTION_TOKEN!}
      layout="list"
      cardOptions={{
        showCover: true,           // 썸네일 표시
        thumbnailPosition: 'right', // 썸네일 위치 (left 또는 right)
      }}
    />
  );
}

리스트 스타일 커스터마이징​

cardOptions={{
  showCover: true,
  thumbnailPosition: 'left',
  listStyle: {
    thumbnailWidth: 200,      // 썸네일 너비
    thumbnailHeight: 120,     // 썸네일 높이
    contentPadding: 20,       // 내용 영역 패딩
    gap: 24,                  // 항목 간 간격
    titleSize: '1.25rem',     // 제목 크기
    descriptionSize: '0.9rem', // 설명 크기
    metaSize: '0.8rem',       // 메타정보 크기
  },
  cardTheme: {
    cardBackground: '#fff',
    cardBorderColor: '#e5e7eb',
    cardRadius: 12,
  },
}}

리스트 옵션 정리​

옵션설명기본값
thumbnailPosition썸네일 위치'right'
listStyle.thumbnailWidth썸네일 너비(px)180
listStyle.thumbnailHeight썸네일 높이(px)100
listStyle.gap항목 간 간격(px)20
listStyle.titleSize제목 폰트 크기'1.25rem'

필터 & 정렬​

테이블, 리스트, 보드 카드 모든 레이아웃에서 필터와 정렬을 사용할 수 있습니다.

필터 예시: 특정 상태만 보기​

<NotionDatabaseById
  databaseId="..."
  token="..."
  layout="list"
  queryOptions={{
    filters: [
      {
        property: '상태',
        type: 'status',
        condition: 'equals',
        value: '진행중',
      },
    ],
  }}
/>

정렬 예시: 최신순​

<NotionDatabaseById
  databaseId="..."
  token="..."
  layout="list"
  queryOptions={{
    sorts: [
      {
        property: '작성일',
        direction: 'descending',  // 내림차순 (최신순)
      },
    ],
  }}
/>

필터 + 정렬 같이 쓰기​

queryOptions={{
  filters: [
    {
      property: '카테고리',
      type: 'select',
      condition: 'equals',
      value: '개발',
    },
  ],
  sorts: [
    {
      property: '작성일',
      direction: 'descending',
    },
  ],
}}

필터 조건 종류​

타입사용 가능한 조건
statusequals, does_not_equal
selectequals, does_not_equal
multi_selectcontains, does_not_contain
checkboxequals
dateequals, before, after, on_or_before, on_or_after
rich_textequals, contains, starts_with
numberequals, greater_than, less_than 등

테이블 vs 리스트 vs 보드 카드​

레이아웃용도특징
table데이터 비교, 관리자여러 컬럼 한눈에
list블로그, 뉴스제목 + 설명 + 썸네일
board-card프로젝트, 갤러리카드 그리드

상황에 맞게 선택하세요!

자주 묻는 질문​

Q. 행 클릭 시 상세 페이지로 이동하고 싶어요​

onRowClick props를 사용하세요:

<NotionDatabaseRenderer
  database={database}
  layout="table"
  onRowClick={(pageId) => {
    // 페이지 이동 또는 모달 열기
    router.push(`/detail/${pageId}`);
  }}
/>

Q. 테이블 컬럼 순서를 바꾸고 싶어요​

visibleColumns 배열 순서대로 표시됩니다:

visibleColumns={['마감일', '상태', '이름']}  // 이 순서로 표시