0
# Notion Types
1
2
Notion Types provides comprehensive TypeScript type definitions for all of Notion's core data structures. This library serves as the foundational type system for the react-notion-x ecosystem and enables type-safe development when working with Notion's API and data formats.
3
4
## Package Information
5
6
- **Package Name**: notion-types
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install notion-types`
10
11
## Core Imports
12
13
```typescript
14
import {
15
Block,
16
Collection,
17
CollectionView,
18
RecordMap,
19
ExtendedRecordMap,
20
User,
21
Formula,
22
PropertyType,
23
Color,
24
Decoration
25
} from "notion-types";
26
```
27
28
For CommonJS:
29
30
```javascript
31
const {
32
Block,
33
Collection,
34
CollectionView,
35
RecordMap,
36
ExtendedRecordMap,
37
User
38
} = require("notion-types");
39
```
40
41
## Basic Usage
42
43
```typescript
44
import { Block, PageBlock, TextBlock, PropertyType } from "notion-types";
45
46
// Work with block types
47
function processBlock(block: Block) {
48
if (block.type === 'page') {
49
const pageBlock = block as PageBlock;
50
console.log('Page title:', pageBlock.properties?.title);
51
} else if (block.type === 'text') {
52
const textBlock = block as TextBlock;
53
console.log('Text content:', textBlock.properties?.title);
54
}
55
}
56
57
// Define collection property schema
58
const propertySchema = {
59
name: PropertyType.title,
60
age: PropertyType.number,
61
email: PropertyType.email,
62
active: PropertyType.checkbox
63
};
64
```
65
66
## Architecture
67
68
Notion Types is organized around several core concepts:
69
70
- **Block System**: 40+ block types representing all Notion content (pages, text, media, databases, etc.)
71
- **Collection System**: Database/collection types with property schemas and views
72
- **Formula System**: Complete formula language with 60+ functions and operators
73
- **Decoration System**: Rich text formatting with 14 formatting types
74
- **Map System**: Aggregate data structures for API responses
75
- **Core Types**: Base types, colors, roles, and utility definitions
76
77
## Capabilities
78
79
### Block Types and Interfaces
80
81
Complete type definitions for all Notion block types including pages, text, media, and interactive content. Covers 40+ block types with full type safety.
82
83
```typescript { .api }
84
type BlockType = 'page' | 'text' | 'header' | 'image' | 'video' | 'code' | 'table' | 'collection_view' | string;
85
86
interface BaseBlock {
87
id: ID;
88
type: BlockType;
89
properties?: any;
90
format?: any;
91
content?: string[];
92
parent_id: ID;
93
version: number;
94
created_time: number;
95
last_edited_time: number;
96
alive: boolean;
97
}
98
99
type Block = PageBlock | TextBlock | HeaderBlock | ImageBlock | VideoBlock | CodeBlock | TableBlock | CollectionViewBlock;
100
```
101
102
[Block Types](./blocks.md)
103
104
### Collection and Database Types
105
106
Type definitions for Notion databases (collections) including schemas, properties, and data validation. Supports all property types and collection configurations.
107
108
```typescript { .api }
109
interface Collection {
110
id: ID;
111
version: number;
112
name: Decoration[];
113
schema: CollectionPropertySchemaMap;
114
icon: string;
115
parent_id: ID;
116
alive: boolean;
117
}
118
119
interface CollectionPropertySchema {
120
name: string;
121
type: PropertyType;
122
options?: SelectOption[];
123
number_format?: NumberFormat;
124
formula?: Formula;
125
}
126
127
type PropertyType = 'title' | 'text' | 'number' | 'select' | 'multi_select' | 'date' | 'person' | 'file' | 'checkbox' | 'url' | 'email' | 'phone_number' | 'formula' | 'relation';
128
```
129
130
[Collections](./collections.md)
131
132
### Collection Views and Display
133
134
Type definitions for all Notion database view types including table, gallery, list, board, and calendar views with their configuration options.
135
136
```typescript { .api }
137
type CollectionViewType = 'table' | 'gallery' | 'list' | 'board' | 'calendar' | 'reducer';
138
139
interface BaseCollectionView {
140
id: ID;
141
type: CollectionViewType;
142
name: string;
143
format: any;
144
version: number;
145
alive: boolean;
146
parent_id: ID;
147
}
148
149
type CollectionView = TableCollectionView | GalleryCollectionView | ListCollectionView | BoardCollectionView | CalendarCollectionView;
150
```
151
152
[Collection Views](./collection-views.md)
153
154
### Formula System
155
156
Complete type definitions for Notion's formula language including all operators, functions, and value types. Supports logic, math, text, and date operations.
157
158
```typescript { .api }
159
type FormulaType = 'constant' | 'property' | 'operator' | 'function' | 'symbol';
160
161
interface BaseFormula {
162
type: FormulaType;
163
result_type: FormulaResultType;
164
}
165
166
type FormulaFunctionType = 'add' | 'subtract' | 'multiply' | 'divide' | 'concat' | 'if' | 'and' | 'or' | 'not' | 'date' | 'now' | 'format';
167
168
type Formula = FunctionFormula | OperatorFormula | ConstantFormula | PropertyFormula | SymbolFormula;
169
```
170
171
[Formulas](./formulas.md)
172
173
### API and Data Structures
174
175
Type definitions for Notion API requests, responses, search operations, and aggregate data structures including RecordMaps and ExtendedRecordMaps.
176
177
```typescript { .api }
178
interface RecordMap {
179
block: BlockMap;
180
collection?: CollectionMap;
181
collection_view?: CollectionViewMap;
182
notion_user?: UserMap;
183
}
184
185
interface SearchParams {
186
ancestorId: string;
187
query: string;
188
filters?: {
189
isDeletedOnly: boolean;
190
excludeTemplates: boolean;
191
isNavigableOnly: boolean;
192
requireEditPermissions: boolean;
193
};
194
limit?: number;
195
}
196
197
interface SearchResults {
198
recordMap: RecordMap;
199
results: SearchResult[];
200
total: number;
201
}
202
```
203
204
[API Types](./api.md)
205
206
### Text Decoration and Formatting
207
208
Rich text decoration system with support for bold, italic, links, colors, mentions, and other formatting options. Includes complete type definitions for all decoration formats.
209
210
```typescript { .api }
211
type Color = 'gray' | 'brown' | 'orange' | 'yellow' | 'teal' | 'blue' | 'purple' | 'pink' | 'red' | 'gray_background' | 'brown_background';
212
213
type SubDecoration = ['b'] | ['i'] | ['s'] | ['c'] | ['_'] | ['a', string] | ['h', Color] | ['u', string] | ['p', string];
214
215
type Decoration = [string] | [string, SubDecoration[]];
216
217
interface FormattedDate {
218
type: 'date' | 'daterange' | 'datetime' | 'datetimerange';
219
start_date: string;
220
start_time?: string;
221
end_date?: string;
222
end_time?: string;
223
}
224
```
225
226
[Text Formatting](./formatting.md)
227
228
### User and Permission Types
229
230
Type definitions for Notion users, roles, and permission systems. Includes user profile information and access control types.
231
232
```typescript { .api }
233
interface User {
234
id: ID;
235
version: number;
236
email: string;
237
given_name: string;
238
family_name: string;
239
profile_photo: string;
240
onboarding_completed: boolean;
241
mobile_onboarding_completed: boolean;
242
}
243
244
type Role = 'editor' | 'reader' | 'none' | 'read_and_write';
245
```
246
247
[Users and Permissions](./users.md)
248
249
## Types
250
251
```typescript { .api }
252
// Core identifier types
253
type ID = string;
254
type PropertyID = string;
255
256
// Generic map wrapper with permissions
257
interface NotionMap<T> {
258
[key: string]: {
259
role: Role;
260
value: T;
261
};
262
}
263
264
// Common map types
265
type BlockMap = NotionMap<Block>;
266
type UserMap = NotionMap<User>;
267
type CollectionMap = NotionMap<Collection>;
268
type CollectionViewMap = NotionMap<CollectionView>;
269
270
// Extended record map with convenience data
271
interface ExtendedRecordMap extends RecordMap {
272
collection: CollectionMap;
273
collection_view: CollectionViewMap;
274
notion_user: UserMap;
275
collection_query: {
276
[collectionId: string]: {
277
[collectionViewId: string]: CollectionQueryResult;
278
};
279
};
280
signed_urls: {
281
[blockId: string]: string;
282
};
283
preview_images?: PreviewImageMap;
284
}
285
286
// Core type aliases
287
type PropertyType = 'title' | 'text' | 'number' | 'select' | 'multi_select' | 'date' | 'person' | 'file' | 'checkbox' | 'url' | 'email' | 'phone_number' | 'formula' | 'relation' | 'rollup' | 'created_time' | 'created_by' | 'last_edited_time' | 'last_edited_by';
288
289
type Role = 'editor' | 'reader' | 'none' | 'read_and_write';
290
```