or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

api.mdblocks.mdcollection-views.mdcollections.mdformatting.mdformulas.mdindex.mdusers.md
tile.json

tessl/npm-notion-types

TypeScript types for core Notion data structures.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/notion-types@7.4.x

To install, run

npx @tessl/cli install tessl/npm-notion-types@7.4.0

index.mddocs/

Notion Types

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.

Package Information

  • Package Name: notion-types
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install notion-types

Core Imports

import {
  Block,
  Collection,
  CollectionView,
  RecordMap,
  ExtendedRecordMap,
  User,
  Formula,
  PropertyType,
  Color,
  Decoration
} from "notion-types";

For CommonJS:

const {
  Block,
  Collection,
  CollectionView,
  RecordMap,
  ExtendedRecordMap,
  User
} = require("notion-types");

Basic Usage

import { Block, PageBlock, TextBlock, PropertyType } from "notion-types";

// Work with block types
function processBlock(block: Block) {
  if (block.type === 'page') {
    const pageBlock = block as PageBlock;
    console.log('Page title:', pageBlock.properties?.title);
  } else if (block.type === 'text') {
    const textBlock = block as TextBlock;
    console.log('Text content:', textBlock.properties?.title);
  }
}

// Define collection property schema
const propertySchema = {
  name: PropertyType.title,
  age: PropertyType.number,
  email: PropertyType.email,
  active: PropertyType.checkbox
};

Architecture

Notion Types is organized around several core concepts:

  • Block System: 40+ block types representing all Notion content (pages, text, media, databases, etc.)
  • Collection System: Database/collection types with property schemas and views
  • Formula System: Complete formula language with 60+ functions and operators
  • Decoration System: Rich text formatting with 14 formatting types
  • Map System: Aggregate data structures for API responses
  • Core Types: Base types, colors, roles, and utility definitions

Capabilities

Block Types and Interfaces

Complete type definitions for all Notion block types including pages, text, media, and interactive content. Covers 40+ block types with full type safety.

type BlockType = 'page' | 'text' | 'header' | 'image' | 'video' | 'code' | 'table' | 'collection_view' | string;

interface BaseBlock {
  id: ID;
  type: BlockType;
  properties?: any;
  format?: any;
  content?: string[];
  parent_id: ID;
  version: number;
  created_time: number;
  last_edited_time: number;
  alive: boolean;
}

type Block = PageBlock | TextBlock | HeaderBlock | ImageBlock | VideoBlock | CodeBlock | TableBlock | CollectionViewBlock;

Block Types

Collection and Database Types

Type definitions for Notion databases (collections) including schemas, properties, and data validation. Supports all property types and collection configurations.

interface Collection {
  id: ID;
  version: number;
  name: Decoration[];
  schema: CollectionPropertySchemaMap;
  icon: string;
  parent_id: ID;
  alive: boolean;
}

interface CollectionPropertySchema {
  name: string;
  type: PropertyType;
  options?: SelectOption[];
  number_format?: NumberFormat;
  formula?: Formula;
}

type PropertyType = 'title' | 'text' | 'number' | 'select' | 'multi_select' | 'date' | 'person' | 'file' | 'checkbox' | 'url' | 'email' | 'phone_number' | 'formula' | 'relation';

Collections

Collection Views and Display

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

type CollectionViewType = 'table' | 'gallery' | 'list' | 'board' | 'calendar' | 'reducer';

interface BaseCollectionView {
  id: ID;
  type: CollectionViewType;
  name: string;
  format: any;
  version: number;
  alive: boolean;
  parent_id: ID;
}

type CollectionView = TableCollectionView | GalleryCollectionView | ListCollectionView | BoardCollectionView | CalendarCollectionView;

Collection Views

Formula System

Complete type definitions for Notion's formula language including all operators, functions, and value types. Supports logic, math, text, and date operations.

type FormulaType = 'constant' | 'property' | 'operator' | 'function' | 'symbol';

interface BaseFormula {
  type: FormulaType;
  result_type: FormulaResultType;
}

type FormulaFunctionType = 'add' | 'subtract' | 'multiply' | 'divide' | 'concat' | 'if' | 'and' | 'or' | 'not' | 'date' | 'now' | 'format';

type Formula = FunctionFormula | OperatorFormula | ConstantFormula | PropertyFormula | SymbolFormula;

Formulas

API and Data Structures

Type definitions for Notion API requests, responses, search operations, and aggregate data structures including RecordMaps and ExtendedRecordMaps.

interface RecordMap {
  block: BlockMap;
  collection?: CollectionMap;
  collection_view?: CollectionViewMap;
  notion_user?: UserMap;
}

interface SearchParams {
  ancestorId: string;
  query: string;
  filters?: {
    isDeletedOnly: boolean;
    excludeTemplates: boolean;
    isNavigableOnly: boolean;
    requireEditPermissions: boolean;
  };
  limit?: number;
}

interface SearchResults {
  recordMap: RecordMap;
  results: SearchResult[];
  total: number;
}

API Types

Text Decoration and Formatting

Rich text decoration system with support for bold, italic, links, colors, mentions, and other formatting options. Includes complete type definitions for all decoration formats.

type Color = 'gray' | 'brown' | 'orange' | 'yellow' | 'teal' | 'blue' | 'purple' | 'pink' | 'red' | 'gray_background' | 'brown_background';

type SubDecoration = ['b'] | ['i'] | ['s'] | ['c'] | ['_'] | ['a', string] | ['h', Color] | ['u', string] | ['p', string];

type Decoration = [string] | [string, SubDecoration[]];

interface FormattedDate {
  type: 'date' | 'daterange' | 'datetime' | 'datetimerange';
  start_date: string;
  start_time?: string;
  end_date?: string;
  end_time?: string;
}

Text Formatting

User and Permission Types

Type definitions for Notion users, roles, and permission systems. Includes user profile information and access control types.

interface User {
  id: ID;
  version: number;
  email: string;
  given_name: string;
  family_name: string;
  profile_photo: string;
  onboarding_completed: boolean;
  mobile_onboarding_completed: boolean;
}

type Role = 'editor' | 'reader' | 'none' | 'read_and_write';

Users and Permissions

Types

// Core identifier types
type ID = string;
type PropertyID = string;

// Generic map wrapper with permissions
interface NotionMap<T> {
  [key: string]: {
    role: Role;
    value: T;
  };
}

// Common map types
type BlockMap = NotionMap<Block>;
type UserMap = NotionMap<User>;
type CollectionMap = NotionMap<Collection>;
type CollectionViewMap = NotionMap<CollectionView>;

// Extended record map with convenience data
interface ExtendedRecordMap extends RecordMap {
  collection: CollectionMap;
  collection_view: CollectionViewMap;
  notion_user: UserMap;
  collection_query: {
    [collectionId: string]: {
      [collectionViewId: string]: CollectionQueryResult;
    };
  };
  signed_urls: {
    [blockId: string]: string;
  };
  preview_images?: PreviewImageMap;
}

// Core type aliases
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';

type Role = 'editor' | 'reader' | 'none' | 'read_and_write';