0
# Block Types
1

2
Complete type definitions for all Notion block types representing pages, text content, media, interactive elements, and structural components.
3

4
## Capabilities
5

6
### Base Block Interface
7

8
All blocks inherit from the BaseBlock interface which provides common properties.
9

10
```typescript { .api }
11
/**
12
 * Base properties shared by all blocks
13
 */
14
interface BaseBlock {
15
  /** Unique block identifier */
16
  id: ID;
17
  /** Type of block */
18
  type: BlockType;
19
  /** Block-specific properties */
20
  properties?: any;
21
  /** Block formatting options */
22
  format?: any;
23
  /** Array of child block IDs */
24
  content?: ID[];
25
  /** Space ID (optional) */
26
  space_id?: ID;
27
  /** Parent block ID */
28
  parent_id: ID;
29
  /** Parent table type */
30
  parent_table: string | 'space' | 'block' | 'table';
31
  /** Block version number */
32
  version: number;
33
  /** Creation timestamp */
34
  created_time: number;
35
  /** Last edit timestamp */
36
  last_edited_time: number;
37
  /** Whether block is active */
38
  alive: boolean;
39
  /** Creator table reference */
40
  created_by_table: string;
41
  /** Creator user ID */
42
  created_by_id: ID;
43
  /** Last editor table reference */
44
  last_edited_by_table: string;
45
  /** Last editor user ID */
46
  last_edited_by_id: ID;
47
}
48
```
49

50
### Block Type Union
51

52
```typescript { .api }
53
/**
54
 * Union type of all supported block types
55
 */
56
type BlockType =
57
  | 'page'
58
  | 'text'
59
  | 'bookmark'
60
  | 'bulleted_list'
61
  | 'numbered_list'
62
  | 'header'
63
  | 'sub_header'
64
  | 'sub_sub_header'
65
  | 'quote'
66
  | 'equation'
67
  | 'to_do'
68
  | 'table_of_contents'
69
  | 'divider'
70
  | 'column_list'
71
  | 'column'
72
  | 'callout'
73
  | 'toggle'
74
  | 'image'
75
  | 'embed'
76
  | 'gist'
77
  | 'video'
78
  | 'figma'
79
  | 'typeform'
80
  | 'replit'
81
  | 'codepen'
82
  | 'excalidraw'
83
  | 'tweet'
84
  | 'maps'
85
  | 'pdf'
86
  | 'audio'
87
  | 'drive'
88
  | 'file'
89
  | 'code'
90
  | 'collection_view'
91
  | 'collection_view_page'
92
  | 'transclusion_container'
93
  | 'transclusion_reference'
94
  | 'alias'
95
  | 'table'
96
  | 'table_row'
97
  | 'external_object_instance'
98
  | 'breadcrumb'
99
  | 'miro'
100
  | string; // fallback for unknown blocks
101

102
/**
103
 * Union type of all specific block interfaces
104
 */
105
type Block =
106
  | TextBlock
107
  | PageBlock
108
  | BulletedListBlock
109
  | NumberedListBlock
110
  | HeaderBlock
111
  | SubHeaderBlock
112
  | SubSubHeaderBlock
113
  | TodoBlock
114
  | TableOfContentsBlock
115
  | DividerBlock
116
  | ColumnListBlock
117
  | ColumnBlock
118
  | QuoteBlock
119
  | EquationBlock
120
  | CodeBlock
121
  | ImageBlock
122
  | VideoBlock
123
  | FigmaBlock
124
  | TypeformBlock
125
  | ReplitBlock
126
  | CodepenBlock
127
  | ExcalidrawBlock
128
  | TweetBlock
129
  | MapsBlock
130
  | AudioBlock
131
  | PdfBlock
132
  | MiroBlock
133
  | GoogleDriveBlock
134
  | FileBlock
135
  | EmbedBlock
136
  | GistBlock
137
  | CalloutBlock
138
  | BookmarkBlock
139
  | ToggleBlock
140
  | CollectionViewBlock
141
  | CollectionViewPageBlock
142
  | SyncBlock
143
  | SyncPointerBlock
144
  | PageLink
145
  | TableBlock
146
  | TableRowBlock
147
  | ExternalObjectInstance
148
  | BreadcrumbInstance;
149
```
150

151
### Base Text Block
152

153
Base interface for blocks containing text content.
154

155
```typescript { .api }
156
/**
157
 * Base interface for text-containing blocks
158
 */
159
interface BaseTextBlock extends BaseBlock {
160
  /** Optional child blocks */
161
  content?: string[];
162
  /** Text properties */
163
  properties?: {
164
    title: Decoration[];
165
  };
166
  /** Text formatting */
167
  format?: {
168
    block_color: Color;
169
  };
170
}
171
```
172

173
### Page Blocks
174

175
```typescript { .api }
176
/**
177
 * Base interface for page-like blocks
178
 */
179
interface BasePageBlock extends BaseBlock {
180
  properties?: {
181
    title: Decoration[];
182
  };
183
  format: {
184
    page_full_width?: boolean;
185
    page_small_text?: boolean;
186
    page_cover_position?: number;
187
    card_cover_position?: number;
188
    block_locked?: boolean;
189
    block_locked_by?: string;
190
    page_cover?: string;
191
    page_icon?: string;
192
    block_color?: Color;
193
  };
194
  permissions: { role: Role; type: string }[];
195
  file_ids?: string[];
196
}
197

198
/**
199
 * Page block representing a Notion page
200
 */
201
interface PageBlock extends BasePageBlock {
202
  type: 'page';
203
}
204
```
205

206
### Text Content Blocks
207

208
```typescript { .api }
209
/**
210
 * Plain text block
211
 */
212
interface TextBlock extends BaseTextBlock {
213
  type: 'text';
214
}
215

216
/**
217
 * Bulleted list item
218
 */
219
interface BulletedListBlock extends BaseTextBlock {
220
  type: 'bulleted_list';
221
}
222

223
/**
224
 * Numbered list item
225
 */
226
interface NumberedListBlock extends BaseTextBlock {
227
  type: 'numbered_list';
228
}
229

230
/**
231
 * Level 1 header
232
 */
233
interface HeaderBlock extends BaseTextBlock {
234
  type: 'header';
235
  format?: {
236
    block_color: Color;
237
    toggleable?: boolean;
238
  };
239
}
240

241
/**
242
 * Level 2 header
243
 */
244
interface SubHeaderBlock extends BaseTextBlock {
245
  type: 'sub_header';
246
  format?: {
247
    block_color: Color;
248
    toggleable?: boolean;
249
  };
250
}
251

252
/**
253
 * Level 3 header
254
 */
255
interface SubSubHeaderBlock extends BaseTextBlock {
256
  type: 'sub_sub_header';
257
  format?: {
258
    block_color: Color;
259
    toggleable?: boolean;
260
  };
261
}
262

263
/**
264
 * Quote block
265
 */
266
interface QuoteBlock extends BaseTextBlock {
267
  type: 'quote';
268
}
269

270
/**
271
 * Mathematical equation block
272
 */
273
interface EquationBlock extends BaseTextBlock {
274
  type: 'equation';
275
}
276

277
/**
278
 * Todo/checkbox block
279
 */
280
interface TodoBlock extends BaseTextBlock {
281
  type: 'to_do';
282
  properties: {
283
    title: Decoration[];
284
    checked: (['Yes'] | ['No'])[];
285
  };
286
}
287
```
288

289
### Media and Content Blocks
290

291
```typescript { .api }
292
/**
293
 * Base interface for media/content blocks
294
 */
295
interface BaseContentBlock extends BaseBlock {
296
  properties: {
297
    source: string[][];
298
    caption?: Decoration[];
299
  };
300
  format?: {
301
    block_alignment: 'center' | 'left' | 'right';
302
    block_width: number;
303
    block_height: number;
304
    display_source: string;
305
    block_full_width: boolean;
306
    block_page_width: boolean;
307
    block_aspect_ratio: number;
308
    block_preserve_scale: boolean;
309
  };
310
  file_ids?: string[];
311
}
312

313
/**
314
 * Image block
315
 */
316
interface ImageBlock extends BaseContentBlock {
317
  type: 'image';
318
}
319

320
/**
321
 * Video block
322
 */
323
interface VideoBlock extends BaseContentBlock {
324
  type: 'video';
325
}
326

327
/**
328
 * Audio block
329
 */
330
interface AudioBlock extends BaseContentBlock {
331
  type: 'audio';
332
}
333

334
/**
335
 * PDF document block
336
 */
337
interface PdfBlock extends BaseContentBlock {
338
  type: 'pdf';
339
}
340

341
/**
342
 * Generic embed block
343
 */
344
interface EmbedBlock extends BaseContentBlock {
345
  type: 'embed';
346
}
347

348
/**
349
 * GitHub Gist block
350
 */
351
interface GistBlock extends BaseContentBlock {
352
  type: 'gist';
353
}
354
```
355

356
### Interactive Blocks
357

358
```typescript { .api }
359
/**
360
 * Code snippet block
361
 */
362
interface CodeBlock extends BaseBlock {
363
  type: 'code';
364
  properties: {
365
    title: Decoration[];
366
    language: Decoration[];
367
    caption: Decoration[];
368
  };
369
}
370

371
/**
372
 * Callout/info block
373
 */
374
interface CalloutBlock extends BaseBlock {
375
  type: 'callout';
376
  format: {
377
    page_icon: string;
378
    block_color: Color;
379
  };
380
  properties: {
381
    title: Decoration[];
382
  };
383
}
384

385
/**
386
 * Collapsible toggle block
387
 */
388
interface ToggleBlock extends BaseBlock {
389
  type: 'toggle';
390
  properties: {
391
    title: Decoration[];
392
  };
393
}
394

395
/**
396
 * Web bookmark block
397
 */
398
interface BookmarkBlock extends BaseBlock {
399
  type: 'bookmark';
400
  properties: {
401
    link: Decoration[];
402
    title: Decoration[];
403
    description: Decoration[];
404
  };
405
  format: {
406
    block_color?: string;
407
    bookmark_icon: string;
408
    bookmark_cover: string;
409
  };
410
}
411
```
412

413
### File and Attachment Blocks
414

415
```typescript { .api }
416
/**
417
 * File attachment block
418
 */
419
interface FileBlock extends BaseBlock {
420
  type: 'file';
421
  properties: {
422
    title: Decoration[];
423
    size: Decoration[];
424
    source: string[][];
425
  };
426
  file_ids?: string[];
427
}
428

429
/**
430
 * Google Drive file block
431
 */
432
interface GoogleDriveBlock extends BaseContentBlock {
433
  type: 'drive';
434
  format: {
435
    drive_status: {
436
      authed: boolean;
437
      last_fetched: number;
438
    };
439
    drive_properties: {
440
      url: string;
441
      icon: string;
442
      title: string;
443
      file_id: string;
444
      trashed: boolean;
445
      version: string;
446
      thumbnail: string;
447
      user_name: string;
448
      modified_time: number;
449
    };
450
    block_alignment: 'center' | 'left' | 'right';
451
    block_width: number;
452
    block_height: number;
453
    display_source: string;
454
    block_full_width: boolean;
455
    block_page_width: boolean;
456
    block_aspect_ratio: number;
457
    block_preserve_scale: boolean;
458
  };
459
  file_ids?: string[];
460
}
461
```
462

463
### Structural Blocks
464

465
```typescript { .api }
466
/**
467
 * Table of contents block
468
 */
469
interface TableOfContentsBlock extends BaseBlock {
470
  type: 'table_of_contents';
471
  format?: {
472
    block_color: Color;
473
  };
474
}
475

476
/**
477
 * Horizontal divider block
478
 */
479
interface DividerBlock extends BaseBlock {
480
  type: 'divider';
481
}
482

483
/**
484
 * Column container block
485
 */
486
interface ColumnListBlock extends BaseBlock {
487
  type: 'column_list';
488
}
489

490
/**
491
 * Individual column block
492
 */
493
interface ColumnBlock extends BaseBlock {
494
  type: 'column';
495
  format: {
496
    column_ratio: number;
497
  };
498
}
499
```
500

501
### Database Blocks
502

503
```typescript { .api }
504
/**
505
 * Database view block
506
 */
507
interface CollectionViewBlock extends BaseContentBlock {
508
  type: 'collection_view';
509
  collection_id?: string;
510
  view_ids: ID[];
511
  format?: BaseContentBlock['format'] & {
512
    collection_pointer?: {
513
      id: string;
514
      spaceId: string;
515
      table: string;
516
    };
517
  };
518
}
519

520
/**
521
 * Full-page database view
522
 */
523
interface CollectionViewPageBlock extends BasePageBlock {
524
  type: 'collection_view_page';
525
  collection_id?: string;
526
  view_ids: ID[];
527
  format: BasePageBlock['format'] & {
528
    collection_pointer?: {
529
      id: string;
530
      spaceId: string;
531
      table: string;
532
    };
533
  };
534
}
535

536
/**
537
 * Table block
538
 */
539
interface TableBlock extends BaseBlock {
540
  type: 'table';
541
  collection_id: string;
542
  format: {
543
    collection_pointer: {
544
      id: string;
545
      table: string;
546
      spaceId: string;
547
    };
548
    table_block_column_format?: {
549
      [column: string]: { width?: number; color?: Color };
550
    };
551
    table_block_column_header: boolean;
552
    table_block_row_header: boolean;
553
    table_block_column_order: string[];
554
  };
555
  view_ids: ID[];
556
}
557

558
/**
559
 * Table row block
560
 */
561
interface TableRowBlock extends BaseBlock {
562
  type: 'table_row';
563
  properties: {
564
    [column: string]: Decoration[];
565
  };
566
}
567
```
568

569
### Sync and Reference Blocks
570

571
```typescript { .api }
572
/**
573
 * Sync block container
574
 */
575
interface SyncBlock extends BaseBlock {
576
  type: 'transclusion_container';
577
}
578

579
/**
580
 * Sync block reference
581
 */
582
interface SyncPointerBlock extends BaseBlock {
583
  type: 'transclusion_reference';
584
  format: {
585
    copied_from_pointer: {
586
      id: string;
587
      spaceid: string;
588
    };
589
    transclusion_reference_pointer: {
590
      id: string;
591
      spaceId: string;
592
    };
593
  };
594
}
595

596
/**
597
 * Page alias/link block
598
 */
599
interface PageLink extends BaseBlock {
600
  type: 'alias';
601
  format: {
602
    alias_pointer: {
603
      id: string;
604
    };
605
  };
606
}
607
```
608

609
### Third-Party Integration Blocks
610

611
```typescript { .api }
612
/**
613
 * Figma embed block
614
 */
615
interface FigmaBlock extends BaseContentBlock {
616
  type: 'figma';
617
}
618

619
/**
620
 * Typeform embed block
621
 */
622
interface TypeformBlock extends BaseContentBlock {
623
  type: 'typeform';
624
}
625

626
/**
627
 * Repl.it embed block
628
 */
629
interface ReplitBlock extends BaseContentBlock {
630
  type: 'replit';
631
}
632

633
/**
634
 * CodePen embed block
635
 */
636
interface CodepenBlock extends BaseContentBlock {
637
  type: 'codepen';
638
}
639

640
/**
641
 * Excalidraw diagram block
642
 */
643
interface ExcalidrawBlock extends BaseContentBlock {
644
  type: 'excalidraw';
645
}
646

647
/**
648
 * Twitter embed block
649
 */
650
interface TweetBlock extends BaseContentBlock {
651
  type: 'tweet';
652
}
653

654
/**
655
 * Map embed block
656
 */
657
interface MapsBlock extends BaseContentBlock {
658
  type: 'maps';
659
}
660

661
/**
662
 * Miro board block
663
 */
664
interface MiroBlock extends BaseContentBlock {
665
  type: 'miro';
666
}
667

668
/**
669
 * External object block
670
 */
671
interface ExternalObjectInstance extends BaseBlock {
672
  type: 'external_object_instance';
673
  format: {
674
    domain: string;
675
    original_url: string;
676
  };
677
}
678

679
/**
680
 * Breadcrumb navigation block
681
 */
682
interface BreadcrumbInstance extends BaseBlock {
683
  type: 'breadcrumb';
684
}
685
```
686

687
**Usage Examples:**
688

689
```typescript
690
import { Block, PageBlock, TextBlock, ImageBlock } from "notion-types";
691

692
// Type guard function
693
function isPageBlock(block: Block): block is PageBlock {
694
  return block.type === 'page';
695
}
696

697
// Process different block types
698
function processBlock(block: Block) {
699
  switch (block.type) {
700
    case 'page':
701
      const pageBlock = block as PageBlock;
702
      console.log('Page:', pageBlock.properties?.title);
703
      break;
704
    case 'text':
705
      const textBlock = block as TextBlock;
706
      console.log('Text:', textBlock.properties?.title);
707
      break;
708
    case 'image':
709
      const imageBlock = block as ImageBlock;
710
      console.log('Image source:', imageBlock.properties.source);
711
      break;
712
  }
713
}
714

715
// Create a text block
716
const textBlock: TextBlock = {
717
  id: 'block-123',
718
  type: 'text',
719
  properties: {
720
    title: [['Hello, world!']]
721
  },
722
  parent_id: 'parent-456',
723
  parent_table: 'block',
724
  version: 1,
725
  created_time: Date.now(),
726
  last_edited_time: Date.now(),
727
  alive: true,
728
  created_by_table: 'notion_user',
729
  created_by_id: 'user-789',
730
  last_edited_by_table: 'notion_user',
731
  last_edited_by_id: 'user-789'
732
};
733
```