Collection Manager

The CollectionManager is the primary entry point for reading and writing collection data. It coordinates the data model, transactions, pagination, and persistence.

initializeCollection

Creates and returns a fully initialized CollectionManager. This is the imperative API — for React, use useCollectionManager instead (see React reference).

import { initializeCollection } from "@blocknote/block-view/core";

const manager = await initializeCollection({
  collectionId: "tasks",
  user: new Reference({ type: "user", id: "alice" }),
  collectionSource,
  documentSource,
  pageSize: 25,
});

InitializeCollectionOptions

interface InitializeCollectionOptions {
  collectionId: string;
  user: Reference;
  collectionSource: CollectionSource;
  documentSource: DocumentSource;
  persistDebounceMs?: number; // default: 250
  maxCommittedEntries?: number; // default: 1000
  maxQueuedEntries?: number; // default: 10000
  offlineMode?: boolean; // default: true
  pageSize?: number; // rows per page
  devtools?: boolean; // default: false
}

Option	Default	Description
collectionId	required	ID of the collection to load
user	required	The current user reference
collectionSource	required	Source for collection schema and metadata
documentSource	required	Source for document CRUD
persistDebounceMs	250	Milliseconds to debounce before persisting
maxCommittedEntries	1000	Max committed operations to keep in memory
maxQueuedEntries	10000	Max queued operations before forcing a flush
offlineMode	true	Queue mutations when offline
pageSize	undefined	Documents per page (undefined = load all)
devtools	false	Enable devtools event emission

Initialization Sequence

1. Fetches the collection schema (including views) from CollectionSource
2. Creates an EntityRegistry and hydrates the collection and views
3. Creates the Transaction, TransactionManager, and PaginationManager
4. Loads the first page of documents for the first view
5. Returns the ready-to-use CollectionManager

CollectionManager

Read API

manager.collection: Collection

The loaded collection with its full schema.

manager.views: CollectionView[]

All views belonging to this collection.

manager.getView(viewId: string): CollectionView

Get a specific view by ID. Throws if not found.

manager.getDocumentIds(viewId: string, propertyDefinitions?: PropertyDefinition[]): string[]

Get the ordered list of document IDs for a view, with client-side filtering and sorting applied. Pass propertyDefinitions if you have custom property types that need their operators evaluated.

Write API

manager.transaction: Transaction

The transaction instance for making mutations. See Transactions guide.

manager.transactionManager: TransactionManager

The transaction manager that handles persistence and rollback.

manager.undoRedo: UndoRedoManager

The undo/redo manager for this collection.

manager.createDocument(options?: {
  viewId?: string;
  id?: string;
  meta?: Record<string, unknown>;
}): void

Convenience method to create a new document. If the view has active filters, the new document is pre-populated with matching values.

await manager.flush(): Promise<void>

Force-flush all pending mutations to the data sources immediately (bypassing the debounce).

Pagination API

manager.isViewInitialized(viewId: string): boolean

Whether the first page of documents has been loaded for this view.

await manager.ensureViewInitialized(viewId: string): Promise<void>

Load the first page if not already loaded.

manager.getPaginationStatus(viewId: string): "fetching" | "idle"

Whether a fetch is currently in progress for this view.

manager.getPaginationState(viewId: string): PaginationState

Full pagination state:

interface PaginationState {
  results: string[]; // document IDs on current page
  totalCount: number | undefined; // total rows if known
  currentPagination: PaginationStrategy | undefined;
  nextPagination: PaginationStrategy | undefined;
  previousPagination: PaginationStrategy | undefined;
}

manager.getTotalCount(viewId: string): number | undefined
manager.hasNextPage(viewId: string): boolean
manager.hasPreviousPage(viewId: string): boolean

await manager.fetchNextPage(viewId: string): Promise<void>
await manager.fetchPreviousPage(viewId: string): Promise<void>
await manager.goToPage(viewId: string, pageNumber: number): Promise<void>

await manager.refreshView(viewId: string, options?: object): Promise<void>

Re-fetch the current page from the source, discarding cached documents.

Lifecycle

manager.dispose(): void

Clean up all subscriptions and internal state. Call this when the component unmounts.

Event Hooks

manager.addHooks({
  paginationStatusChanged: ({ viewId, status }) => { ... },
  documentsHydrated: ({ viewId, documentIds }) => { ... },
  mutationsCommitted: ({ entries }) => { ... },
  mutationsRolledBack: ({ entries }) => { ... },
  viewsInvalidated: ({ viewIds }) => { ... },
  error: ({ error, context }) => { ... },
  disposed: () => { ... },
});

Hook	Fires when
paginationStatusChanged	A view starts or finishes fetching
documentsHydrated	New documents are loaded into the registry
mutationsCommitted	Operations are successfully persisted to sources
mutationsRolledBack	Operations failed to persist and were rolled back
viewsInvalidated	Views need to be re-rendered
error	An error occurs (context: "initialization", "pagination", or "mutation")
disposed	The manager has been disposed

Transaction

The mutation API. All model changes go through here.

const transaction = manager.transaction;

Methods

transaction.update(entity, changes, options?)

Update an entity’s properties. Returns { meta(data) } for attaching metadata to the operation.

transaction.create(entityType, parentEntity, id?, data?, options?)

Create a new entity. entityType is one of: "collectionViewId", "collectionId", "documentId", "propertyId", "propertyValueId".

transaction.delete(entity, options?)

Delete an entity.

Example

// Update a cell value
const doc = collection.documents.get("doc-1");
const prop = doc.getProp("status");
transaction.update(prop, { value: "done" });

// Create a new column
transaction.create("propertyId", collection, "due-date", {
  label: "Due Date",
  type: "date",
});

// Delete a document
transaction.delete(doc);

UndoRedoManager

Groups operations into time-windowed batches (500ms) for undo/redo.

const undoRedo = manager.undoRedo;

Methods

Method	Returns	Description
undo()	void	Undo the last batch
redo()	void	Redo the last undone batch
canUndo()	boolean	Whether there’s something to undo
canRedo()	boolean	Whether there’s something to redo
clearHistory()	void	Clear all undo/redo history
getUndoStack()	BatchedOperations[]	Current undo stack
getRedoStack()	BatchedOperations[]	Current redo stack

Batching

Operations performed within 500ms are grouped into a single undo unit:

// Rapid edits → one undo unit
transaction.update(val1, { value: "a" });
transaction.update(val2, { value: "b" });

// After 500ms gap → separate undo unit
setTimeout(() => {
  transaction.update(val3, { value: "c" });
}, 600);

TransactionManager

Handles the persistence pipeline. You rarely need to interact with it directly.

const txManager = manager.transactionManager;

Key behaviors:

• Debounces mutations (default 250ms)
• Groups operations by entity type for parallel persistence
• Automatic rollback on failure (applies inverse operations)
• Tracks committed operations (up to maxCommittedEntries)