Sources

Data sources define how the library loads and persists data. There are two interfaces (CollectionSource and DocumentSource) and four built-in implementations.

CollectionSource

Fetches and updates collection schema and view metadata.

import type { CollectionSource } from "@blocknote/block-view/core/sources";

interface CollectionSource {
  fetch(collectionId: string): Promise<CollectionJSON>;
  update(ctx: CollectionContext, changes: Partial<CollectionJSON>): Promise<void>;
  subscribe?: (
    collectionId: string,
    applyRemote: (events: CollectionSourceEvent[]) => void,
  ) => () => void;
}

Method	Description
fetch	Load the full collection schema, views, and metadata
update	Persist changes to collection schema or view configuration
subscribe	Optional. Subscribe to remote changes. Returns an unsubscribe function

CollectionContext

interface CollectionContext {
  collectionId: string;
  collectionViewId?: string;
  propertyId?: string;
}

CollectionSourceEvent

type CollectionSourceEvent = {
  type: "update";
  collection: Pick<CollectionJSON, "id"> & Partial<Omit<CollectionJSON, "documents">>;
};

DocumentSource

CRUD operations for documents with paginated fetching.

import type { DocumentSource } from "@blocknote/block-view/core/sources";

interface DocumentSource {
  fetch(collectionId: string, params: FetchDocumentsParams): Promise<PageResult<DocumentJSON>>;
  create(ctx: { collectionId: string; document: Document }): Promise<void>;
  update(ctx: DocumentContext, changes: Partial<DocumentJSON>): Promise<void>;
  delete(ctx: { collectionId: string; documentId: string }): Promise<void>;
  subscribe?: (
    collectionId: string,
    applyRemote: (events: DocumentSourceEvent[]) => void,
  ) => () => void;
}

Method	Description
fetch	Load a page of documents with optional filters/sorts
create	Persist a new document
update	Persist changes to an existing document
delete	Remove a document
subscribe	Optional. Subscribe to remote document changes

DocumentContext

interface DocumentContext {
  collectionId: string;
  documentId: string;
  propertyValueId?: string;
}

DocumentSourceEvent

type DocumentSourceEvent =
  | { type: "upsert"; document: Pick<DocumentJSON, "id"> & Partial<DocumentJSON> }
  | { type: "delete"; documentId: string };

Pagination Types

import type {
  Cursor,
  Offset,
  PaginationStrategy,
  PageResult,
  SortParam,
  FetchDocumentsParams,
} from "@blocknote/block-view/core/sources";

PaginationStrategy

type Cursor = { cursor: string };
type Offset = { offset: number; limit?: number };
type PaginationStrategy = Cursor | Offset;

PageResult

type PageResult<T> = {
  data: T[];
  totalCount?: number;
  next?: PaginationStrategy;
  previous?: PaginationStrategy;
};

The next and previous fields tell the library how to fetch adjacent pages. Set next to undefined to indicate the last page.

FetchDocumentsParams

type FetchDocumentsParams = {
  collection: CollectionJSON;
  viewId: string;
  sorts?: SortParam[];
  filters?: Filter[];
  pagination?: PaginationStrategy;
};

SortParam

type SortParam = {
  propertyId: string;
  direction: "asc" | "desc";
};

JSON Types

These are the serialized shapes used by data sources.

CollectionJSON

type CollectionJSON = {
  id: string;
  name: string;
  schema: Record<string, PropertyJSON>;
  documents: DocumentJSON[];
  size: number;
  createdBy: { type: string; id: string };
  createdAt: number;
  updatedAt: number;
  updatedBy: { type: string; id: string };
  role: "editor" | "reader";
  viewId: string;
  views: CollectionViewJSON[];
};

CollectionViewJSON

type CollectionViewJSON = {
  id: string;
  type: "table" | "kanban" | "calendar" | "gallery";
  collectionId: string;
  manualSortOrder: string[];
  filters: Filter[] | undefined;
  sorts: Array<{ property: PropertyJSON; desc: boolean }> | undefined;
  columns: Array<{ propertyId: string; width?: number; visible?: boolean }> | undefined;
  createdBy: { type: string; id: string };
  createdAt: number;
  updatedAt: number;
  updatedBy: { type: string; id: string };
  role: "editor" | "reader";
};

DocumentJSON

type DocumentJSON = {
  id: string;
  collectionId: string;
  props: Record<string, { value: string; ref?: { type: string; id: string } }>;
  createdBy: { type: string; id: string };
  createdAt: number;
  updatedBy: { type: string; id: string };
  updatedAt: number;
  role: "editor" | "reader";
  meta?: Record<string, unknown>;
};

Built-in Implementations

InMemoryCollectionSource / InMemoryDocumentSource

Data lives in memory. No network calls.

import {
  InMemoryCollectionSource,
  InMemoryDocumentSource,
} from "@blocknote/block-view/core/sources/in-memory";

const collectionSource = new InMemoryCollectionSource(collectionJSON);
const documentSource = new InMemoryDocumentSource(documentsArray);

Constructor param	Type	Description
InMemoryCollectionSource(data)	CollectionJSON	The full collection schema
InMemoryDocumentSource(data)	DocumentJSON[]	Array of document objects

RestCollectionSource / RestDocumentSource

Maps to standard REST endpoints.

import { RestCollectionSource, RestDocumentSource } from "@blocknote/block-view/core/sources/rest";

const source = new RestCollectionSource(options);

RestSourceOptions

interface RestSourceOptions {
  baseUrl?: string;
  collectionId?: string;
  routes?: RestSourceRoutes;
  fetch?: FetchFn;
}

RestSourceRoutes

interface RestSourceRoutes {
  collection?: (collectionId: string) => string;
  documents?: (collectionId: string) => string;
  document?: (collectionId: string, documentId: string) => string;
}

FetchFn

type FetchFn = (request: Request) => Promise<Response>;

BroadcastCollectionSource / BroadcastDocumentSource

Decorator sources that add cross-tab synchronization via BroadcastChannel.

import {
  BroadcastCollectionSource,
  BroadcastDocumentSource,
} from "@blocknote/block-view/core/sources/broadcast";

// Wrap any source
const collectionSource = new BroadcastCollectionSource(innerCollectionSource);
const documentSource = new BroadcastDocumentSource(innerDocumentSource);

All CRUD operations are delegated to the inner source. Changes are broadcast to other tabs and applied via the subscribe mechanism.

YjsCollectionSource / YjsDocumentSource

CRDT-backed sources using Yjs.

import {
  YjsCollectionSource,
  YjsDocumentSource,
  writeCollection,
  writeDocument,
} from "@blocknote/block-view/core/sources/yjs";

Constructor param	Type	Description
YjsCollectionSource(ydoc)	Y.Doc	Yjs document
YjsDocumentSource(ydoc)	Y.Doc	Yjs document

Yjs Helper Functions

Function	Description
writeCollection(ydoc, data)	Write collection schema to a Y.Doc
writeDocument(ydoc, data)	Write a document to a Y.Doc
hydrateCollection(ydoc)	Read collection schema from a Y.Doc
hydrateDocument(ydoc, docId)	Read a document from a Y.Doc
writeView(ydoc, data)	Write view configuration to a Y.Doc
writeProperty(ydoc, data)	Write a property definition to a Y.Doc
writeFilters(ydoc, viewId, filters)	Write filters to a Y.Doc
updateCollection(ydoc, changes)	Update collection fields in a Y.Doc
updateDocument(ydoc, docId, changes)	Update document fields in a Y.Doc