0
# Collection Views
1

2
Type definitions for all Notion database view types including table, gallery, list, board, and calendar views with their configuration options and display settings.
3

4
## Capabilities
5

6
### Base Collection View
7

8
All collection views inherit from the BaseCollectionView interface.
9

10
```typescript { .api }
11
/**
12
 * Base properties for all collection views
13
 */
14
interface BaseCollectionView {
15
  /** View identifier */
16
  id: ID;
17
  /** View type */
18
  type: CollectionViewType;
19
  /** View name */
20
  name: string;
21
  /** View-specific formatting */
22
  format: any;
23
  /** View version */
24
  version: number;
25
  /** Whether view is active */
26
  alive: boolean;
27
  /** Parent collection ID */
28
  parent_id: ID;
29
  /** Parent table type */
30
  parent_table: string;
31
  /** Legacy query format */
32
  query?: any;
33
  /** Current query format */
34
  query2: {
35
    /** Filter criteria */
36
    filter?: any;
37
    /** Aggregation functions */
38
    aggregations?: object[];
39
    /** Grouping property */
40
    group_by: string;
41
  };
42
}
43
```
44

45
### View Types
46

47
```typescript { .api }
48
/**
49
 * Types of collection views supported by Notion
50
 */
51
type CollectionViewType =
52
  | 'table'      // Table view
53
  | 'gallery'    // Gallery/card view
54
  | 'list'       // List view
55
  | 'board'      // Kanban board view
56
  | 'calendar'   // Calendar view
57
  | 'reducer';   // Aggregated view
58

59
/**
60
 * Union type of all collection view interfaces
61
 */
62
type CollectionView =
63
  | TableCollectionView
64
  | GalleryCollectionView
65
  | ListCollectionView
66
  | BoardCollectionView
67
  | CalendarCollectionView
68
  | ReducerCollectionView;
69
```
70

71
### Cover Configuration
72

73
```typescript { .api }
74
/**
75
 * Cover image source types
76
 */
77
type CollectionCardCoverType =
78
  | 'page_cover'     // Use page cover image
79
  | 'page_content'   // Use page content as cover
80
  | 'property'       // Use property value as cover
81
  | 'none'           // No cover
82
  | 'file';          // Use file as cover
83

84
/**
85
 * Cover image sizes
86
 */
87
type CollectionCardCoverSize = 'small' | 'medium' | 'large';
88

89
/**
90
 * Cover image aspect ratio handling
91
 */
92
type CollectionCardCoverAspect = 'cover' | 'contain';
93

94
/**
95
 * Card cover configuration
96
 */
97
interface CollectionCardCover {
98
  /** Cover source type */
99
  type: CollectionCardCoverType;
100
  /** Property to use as cover (if type is 'property') */
101
  property?: string;
102
}
103
```
104

105
### Table View
106

107
```typescript { .api }
108
/**
109
 * Table view configuration
110
 */
111
interface TableCollectionView extends BaseCollectionView {
112
  type: 'table';
113
  /** Table-specific formatting */
114
  format: {
115
    /** Whether to wrap table content */
116
    table_wrap: boolean;
117
    /** Column configuration */
118
    table_properties: Array<{
119
      property: string;
120
      visible: boolean;
121
      width: number;
122
    }>;
123
  };
124
  /** Page sort order */
125
  page_sort: string[];
126
}
127
```
128

129
### Gallery View
130

131
```typescript { .api }
132
/**
133
 * Gallery view configuration
134
 */
135
interface GalleryCollectionView extends BaseCollectionView {
136
  type: 'gallery';
137
  /** Gallery-specific formatting */
138
  format: {
139
    /** Card cover settings */
140
    gallery_cover: CollectionCardCover;
141
    /** Cover size */
142
    gallery_cover_size: CollectionCardCoverSize;
143
    /** Cover aspect ratio */
144
    gallery_cover_aspect: CollectionCardCoverAspect;
145
    /** Property visibility */
146
    gallery_properties: Array<{
147
      property: string;
148
      visible: boolean;
149
    }>;
150
  };
151
}
152
```
153

154
### List View
155

156
```typescript { .api }
157
/**
158
 * List view configuration
159
 */
160
interface ListCollectionView extends BaseCollectionView {
161
  type: 'list';
162
  /** List-specific formatting */
163
  format: {
164
    /** Property visibility */
165
    list_properties: Array<{
166
      property: string;
167
      visible: boolean;
168
    }>;
169
  };
170
}
171
```
172

173
### Board View
174

175
```typescript { .api }
176
/**
177
 * Board/Kanban view configuration
178
 */
179
interface BoardCollectionView extends BaseCollectionView {
180
  type: 'board';
181
  /** Board-specific formatting */
182
  format: {
183
    /** Card cover settings */
184
    board_cover: CollectionCardCover;
185
    /** Cover size */
186
    board_cover_size: CollectionCardCoverSize;
187
    /** Cover aspect ratio */
188
    board_cover_aspect: CollectionCardCoverAspect;
189
    /** Property visibility */
190
    board_properties: Array<{
191
      property: string;
192
      visible: boolean;
193
    }>;
194
    /** Board grouping configuration */
195
    board_groups2: Array<{
196
      property: string;
197
      hidden: boolean;
198
      value: {
199
        type: PropertyType;
200
        value: string;
201
      };
202
    }>;
203
    /** Board column configuration */
204
    board_columns: Array<{
205
      property: string;
206
      hidden: boolean;
207
      value: {
208
        type: PropertyType;
209
        value: string;
210
      };
211
    }>;
212
  };
213
}
214
```
215

216
### Calendar View
217

218
```typescript { .api }
219
/**
220
 * Calendar view configuration
221
 */
222
interface CalendarCollectionView extends BaseCollectionView {
223
  type: 'calendar';
224
  // Additional properties TODO in source
225
}
226
```
227

228
### Reducer View
229

230
```typescript { .api }
231
/**
232
 * Aggregated view configuration
233
 */
234
interface ReducerCollectionView extends BaseCollectionView {
235
  type: 'reducer';
236
  /** Aggregation results */
237
  reducerResults: {
238
    collection_group_results: object;
239
  };
240
  /** Size hint for rendering */
241
  sizeHint: number;
242
}
243
```
244

245
**Usage Examples:**
246

247
```typescript
248
import { 
249
  CollectionView,
250
  TableCollectionView,
251
  GalleryCollectionView,
252
  BoardCollectionView,
253
  CollectionViewType,
254
  CollectionCardCover 
255
} from "notion-types";
256

257
// Create a table view
258
const tableView: TableCollectionView = {
259
  id: "view-123",
260
  type: "table",
261
  name: "All Users",
262
  format: {
263
    table_wrap: true,
264
    table_properties: [
265
      { property: "title", visible: true, width: 200 },
266
      { property: "email", visible: true, width: 250 },
267
      { property: "status", visible: true, width: 120 },
268
      { property: "age", visible: false, width: 80 }
269
    ]
270
  },
271
  version: 1,
272
  alive: true,
273
  parent_id: "collection-456",
274
  parent_table: "collection",
275
  page_sort: [],
276
  query2: {
277
    group_by: "status"
278
  }
279
};
280

281
// Create a gallery view
282
const galleryView: GalleryCollectionView = {
283
  id: "view-789",
284
  type: "gallery",
285
  name: "User Cards",
286
  format: {
287
    gallery_cover: {
288
      type: "property",
289
      property: "profile_image"
290
    },
291
    gallery_cover_size: "medium",
292
    gallery_cover_aspect: "cover",
293
    gallery_properties: [
294
      { property: "title", visible: true },
295
      { property: "email", visible: true },
296
      { property: "status", visible: true }
297
    ]
298
  },
299
  version: 1,
300
  alive: true,
301
  parent_id: "collection-456",
302
  parent_table: "collection",
303
  query2: {
304
    group_by: "status"
305
  }
306
};
307

308
// Create a board view
309
const boardView: BoardCollectionView = {
310
  id: "view-101",
311
  type: "board",
312
  name: "Status Board",
313
  format: {
314
    board_cover: {
315
      type: "page_cover"
316
    },
317
    board_cover_size: "small",
318
    board_cover_aspect: "cover",
319
    board_properties: [
320
      { property: "title", visible: true },
321
      { property: "email", visible: true }
322
    ],
323
    board_groups2: [
324
      {
325
        property: "status",
326
        hidden: false,
327
        value: { type: "select", value: "Active" }
328
      },
329
      {
330
        property: "status",
331
        hidden: false,
332
        value: { type: "select", value: "Pending" }
333
      }
334
    ],
335
    board_columns: [
336
      {
337
        property: "status",
338
        hidden: false,
339
        value: { type: "select", value: "Active" }
340
      }
341
    ]
342
  },
343
  version: 1,
344
  alive: true,
345
  parent_id: "collection-456",
346
  parent_table: "collection",
347
  query2: {
348
    group_by: "status"
349
  }
350
};
351

352
// Type guard functions
353
function isTableView(view: CollectionView): view is TableCollectionView {
354
  return view.type === 'table';
355
}
356

357
function isGalleryView(view: CollectionView): view is GalleryCollectionView {
358
  return view.type === 'gallery';
359
}
360

361
// Process different view types
362
function configureView(view: CollectionView) {
363
  switch (view.type) {
364
    case 'table':
365
      const tableView = view as TableCollectionView;
366
      console.log('Table columns:', tableView.format.table_properties.length);
367
      break;
368
    case 'gallery':
369
      const galleryView = view as GalleryCollectionView;
370
      console.log('Gallery cover:', galleryView.format.gallery_cover.type);
371
      break;
372
    case 'board':
373
      const boardView = view as BoardCollectionView;
374
      console.log('Board groups:', boardView.format.board_groups2.length);
375
      break;
376
  }
377
}
378
```