Open History to see the last commit
1---
2title: Overview
3id: overview
4---
5
6# TanStack DB - Documentation
7
8Welcome to the TanStack DB documentation.
9
10TanStack DB is the reactive client store for your API. It solves the problems of building fast, modern apps, helping you:
11
12- avoid endpoint sprawl and network waterfalls by loading data into normalized collections
13- optimise client performance with sub-millisecond live queries and real-time reactivity
14- take the network off the interaction path with instant optimistic writes
15
16Data loading is optimized. Interactions feel instantaneous. Your backend stays simple and your app stays blazing fast. No matter how much data you load.
17
18## Remove the complexity from building fast, modern apps
19
20TanStack DB lets you query your data however your components need it, with a blazing-fast local query engine, real-time reactivity and instant optimistic updates.
21
22Instead of choosing between the least of two evils:
23
241. **view-specific APIs** - complicating your backend and leading to network waterfalls
252. **load everything and filter** - leading to slow loads and sluggish client performance
26
27TanStack DB enables a new way:
28
293. **normalized collections** - keep your backend simple
304. **query-driven sync** - optimizes your data loading
315. **sub-millisecond live queries** - keep your app fast and responsive
32
33It extends TanStack Query with collections, live queries and optimistic mutations, working seamlessly with REST APIs, sync engines, or any data source.
34
35## Contents
36
37- [How it works](#how-it-works) — understand the TanStack DB development model and how the pieces fit together
38- [API reference](#api-reference) — for the primitives and function interfaces
39- [Usage examples](#usage-examples) — examples of common usage patterns
40- [More info](#more-info) — where to find support and more information
41
42## How it works
43
44TanStack DB works by:
45
46- [defining collections](#defining-collections) typed sets of objects that can be populated with data
47- [using live queries](#using-live-queries) to query data from/across collections
48- [making optimistic mutations](#making-optimistic-mutations) using transactional mutators
49
50```tsx
51// Define collections to load data into
52const todoCollection = createCollection({
53 // ...your config
54 onUpdate: updateMutationFn,
55})
56
57const Todos = () => {
58 // Bind data using live queries
59 const { data: todos } = useLiveQuery((q) =>
60 q.from({ todo: todoCollection }).where(({ todo }) => not(todo.completed))
61 )
62
63 const complete = (todo) => {
64 // Instantly applies optimistic state
65 todoCollection.update(todo.id, (draft) => {
66 draft.completed = true
67 })
68 }
69
70 return (
71 <ul>
72 {todos.map((todo) => (
73 <li key={todo.id} onClick={() => complete(todo)}>
74 {todo.text}
75 </li>
76 ))}
77 </ul>
78 )
79}
80```
81
82### Defining collections
83
84Collections are typed sets of objects that can be populated with data. They're designed to de-couple loading data into your app from binding data to your components.
85
86Collections can be populated in many ways, including:
87
88- fetching data, for example [from API endpoints using TanStack Query](https://tanstack.com/query/latest)
89- syncing data, for example [using a sync engine like ElectricSQL](https://electric-sql.com/) or [PowerSync](https://powersync.com)
90- storing local data, for example [using localStorage for user preferences and settings](./collections/local-storage-collection.md) or [in-memory client data or UI state](./collections/local-only-collection.md)
91- from live collection queries, creating [derived collections as materialised views](#using-live-queries)
92
93Once you have your data in collections, you can query across them using live queries in your components.
94
95#### Sync Modes
96
97Collections support three sync modes to optimize data loading:
98
99- **Eager mode** (default): Loads entire collection upfront. Best for <10k rows of mostly static data like user preferences or small reference tables.
100- **On-demand mode**: Loads only what queries request. Best for large datasets (>50k rows), search interfaces, and catalogs where most data won't be accessed.
101- **Progressive mode**: Loads query subset immediately, syncs full dataset in background. Best for collaborative apps needing instant first paint AND sub-millisecond queries.
102
103With on-demand mode, your component's query becomes the API call:
104
105```tsx
106const productsCollection = createCollection(
107 queryCollectionOptions({
108 queryKey: ['products'],
109 queryFn: async (ctx) => {
110 // Query predicates passed automatically in ctx.meta
111 const params = parseLoadSubsetOptions(ctx.meta?.loadSubsetOptions)
112 return api.getProducts(params) // e.g., GET /api/products?category=electronics&price_lt=100
113 },
114 syncMode: 'on-demand', // ← Enable query-driven sync
115 })
116)
117```
118
119TanStack DB automatically collapses duplicate requests, performs delta loading when expanding queries, optimizes joins into minimal batched requests, and respects your TanStack Query cache policies. You often end up with _fewer_ network requests than custom view-specific APIs.
120
121See the [Query Collection documentation](./collections/query-collection.md#queryfn-and-predicate-push-down) for full predicate mapping details.
122
123### Using live queries
124
125Live queries are used to query data out of collections. Live queries are reactive: when the underlying data changes in a way that would affect the query result, the result is incrementally updated and returned from the query, triggering a re-render.
126
127TanStack DB live queries are implemented using [d2ts](https://github.com/electric-sql/d2ts), a TypeScript implementation of differential dataflow. This allows the query results to update _incrementally_ (rather than by re-running the whole query). This makes them blazing fast, usually sub-millisecond, even for highly complex queries.
128
129**Performance:** Updating one row in a sorted 100,000-item collection completes in ~0.7ms on an M1 Pro MacBook—fast enough that optimistic updates feel truly instantaneous, even with complex queries and large datasets.
130
131Live queries support joins across collections. This allows you to:
132
1331. load normalised data into collections and then de-normalise it through queries; simplifying your backend by avoiding the need for bespoke API endpoints that match your client
1342. join data from multiple sources; for example, syncing some data out of a database, fetching some other data from an external API and then joining these into a unified data model for your front-end code
135
136Every query returns another collection which can _also_ be queried.
137
138For more details on live queries, see the [Live Queries](./guides/live-queries.md) documentation.
139
140### Making optimistic mutations
141
142Collections support `insert`, `update` and `delete` operations. When called, by default they trigger the corresponding `onInsert`, `onUpdate`, `onDelete` handlers which are responsible for writing the mutation to the backend.
143
144```ts
145// Define collection with persistence handlers
146const todoCollection = createCollection({
147 id: "todos",
148 // ... other config
149 onUpdate: async ({ transaction }) => {
150 const { original, changes } = transaction.mutations[0]
151 await api.todos.update(original.id, changes)
152 },
153})
154
155// Immediately applies optimistic state
156todoCollection.update(todo.id, (draft) => {
157 draft.completed = true
158})
159```
160
161The collection maintains optimistic state separately from synced data. When live queries read from the collection, they see a local view that overlays the optimistic mutations on top of the immutable synced data.
162
163The optimistic state is held until the handler resolves, at which point the data is persisted to the server and synced back. If the handler throws an error, the optimistic state is rolled back.
164
165For more complex mutations, you can create custom actions with `createOptimisticAction` or custom transactions with `createTransaction`. See the [Mutations guide](./guides/mutations.md) for details.
166
167### Uni-directional data flow
168
169This combines to support a model of uni-directional data flow, extending the redux/flux style state management pattern beyond the client, to take in the server as well:
170
171<figure>
172 <a href="https://raw.githubusercontent.com/TanStack/db/main/docs/unidirectional-data-flow.lg.png" target="_blank">
173 <img src="https://raw.githubusercontent.com/TanStack/db/main/docs/unidirectional-data-flow.png" />
174 </a>
175</figure>
176
177With an instant inner loop of optimistic state, superseded in time by the slower outer loop of persisting to the server and syncing the updated server state back into the collection.
178
179## API reference
180
181### Collections
182
183TanStack DB provides several built-in collection types for different data sources and use cases. Each collection type has its own detailed documentation page:
184
185#### Built-in Collection Types
186
187**Fetch Collections**
188
189- **[QueryCollection](./collections/query-collection.md)** — Load data into collections using TanStack Query for REST APIs and data fetching.
190
191**Sync Collections**
192
193- **[ElectricCollection](./collections/electric-collection.md)** — Sync data into collections from Postgres using ElectricSQL's real-time sync engine.
194
195- **[TrailBaseCollection](./collections/trailbase-collection.md)** — Sync data into collections using TrailBase's self-hosted backend with real-time subscriptions.
196
197- **[RxDBCollection](./collections/rxdb-collection.md)** — Integrate with RxDB for offline-first local persistence with powerful replication and sync capabilities.
198
199- **[PowerSyncCollection](./collections/powersync-collection.md)** — Sync with PowerSync's SQLite-based database for offline-first persistence with real-time synchronization with PostgreSQL, MongoDB, and MySQL backends.
200
201**Local Collections**
202
203- **[LocalStorageCollection](./collections/local-storage-collection.md)** — Store small amounts of local-only state that persists across sessions and syncs across browser tabs.
204
205- **[LocalOnlyCollection](./collections/local-only-collection.md)** — Manage in-memory client data or UI state that doesn't need persistence or cross-tab sync.
206
207#### Collection Schemas
208
209All collections optionally (though strongly recommended) support adding a `schema`.
210
211If provided, this must be a [Standard Schema](https://standardschema.dev) compatible schema instance, such as [Zod](https://zod.dev), [Valibot](https://valibot.dev), [ArkType](https://arktype.io), or [Effect](https://effect.website/docs/schema/introduction/).
212
213**What schemas do:**
214
2151. **Runtime validation** - Ensures data meets your constraints before entering the collection
2162. **Type transformations** - Convert input types to rich output types (e.g., string → Date)
2173. **Default values** - Automatically populate missing fields
2184. **Type safety** - Infer TypeScript types from your schema
219
220**Example:**
221```typescript
222const todoSchema = z.object({
223 id: z.string(),
224 text: z.string(),
225 completed: z.boolean().default(false),
226 created_at: z.string().transform(val => new Date(val)), // string → Date
227 priority: z.number().default(0)
228})
229
230const collection = createCollection(
231 queryCollectionOptions({
232 schema: todoSchema,
233 // ...
234 })
235)
236
237// Users provide simple inputs
238collection.insert({
239 id: "1",
240 text: "Buy groceries",
241 created_at: "2024-01-01T00:00:00Z" // string
242 // completed and priority filled automatically
243})
244
245// Collection stores and returns rich types
246const todo = collection.get("1")
247console.log(todo.created_at.getFullYear()) // It's a Date!
248console.log(todo.completed) // false (default)
249```
250
251The collection will use the schema for its type inference. If you provide a schema, you cannot also pass an explicit type parameter (e.g., `createCollection<Todo>()`).
252
253**Learn more:** See the [Schemas guide](./guides/schemas.md) for comprehensive documentation on schema validation, type transformations, and best practices.
254
255#### Creating Custom Collection Types
256
257You can create your own collection types by implementing the `Collection` interface found in [`../packages/db/src/collection/index.ts`](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts).
258
259See the existing implementations in [`../packages/db`](https://github.com/TanStack/db/tree/main/packages/db), [`../packages/query-db-collection`](https://github.com/TanStack/db/tree/main/packages/query-db-collection), [`../packages/electric-db-collection`](https://github.com/TanStack/db/tree/main/packages/electric-db-collection), [`../packages/trailbase-db-collection`](https://github.com/TanStack/db/tree/main/packages/trailbase-db-collection) and [`../packages/powersync-db-collection`](https://github.com/TanStack/db/tree/main/packages/powersync-db-collection) for reference. Also see the [Collection Options Creator guide](./guides/collection-options-creator.md) for a pattern to create reusable collection configuration factories.
260
261### Live queries
262
263#### `useLiveQuery` hook
264
265Use the `useLiveQuery` hook to assign live query results to a state variable in your React components:
266
267```ts
268import { useLiveQuery } from '@tanstack/react-db'
269import { eq } from '@tanstack/db'
270
271const Todos = () => {
272 const { data: todos } = useLiveQuery((q) =>
273 q
274 .from({ todo: todoCollection })
275 .where(({ todo }) => eq(todo.completed, false))
276 .orderBy(({ todo }) => todo.created_at, 'asc')
277 .select(({ todo }) => ({
278 id: todo.id,
279 text: todo.text
280 }))
281 )
282
283 return <List items={ todos } />
284}
285```
286
287You can also query across collections with joins:
288
289```ts
290import { useLiveQuery } from '@tanstack/react-db'
291import { eq } from '@tanstack/db'
292
293const Todos = () => {
294 const { data: todos } = useLiveQuery((q) =>
295 q
296 .from({ todos: todoCollection })
297 .join(
298 { lists: listCollection },
299 ({ todos, lists }) => eq(lists.id, todos.listId),
300 'inner'
301 )
302 .where(({ lists }) => eq(lists.active, true))
303 .select(({ todos, lists }) => ({
304 id: todos.id,
305 title: todos.title,
306 listName: lists.name
307 }))
308 )
309
310 return <List items={ todos } />
311}
312```
313
314#### `useLiveSuspenseQuery` hook
315
316For React Suspense support, use `useLiveSuspenseQuery`. This hook suspends rendering during initial data load and guarantees that `data` is always defined:
317
318```tsx
319import { useLiveSuspenseQuery } from '@tanstack/react-db'
320import { Suspense } from 'react'
321
322const Todos = () => {
323 // data is always defined - no need for optional chaining
324 const { data: todos } = useLiveSuspenseQuery((q) =>
325 q
326 .from({ todo: todoCollection })
327 .where(({ todo }) => eq(todo.completed, false))
328 )
329
330 return <List items={ todos } />
331}
332
333const App = () => (
334 <Suspense fallback={<div>Loading...</div>}>
335 <Todos />
336 </Suspense>
337)
338```
339
340See the [React Suspense section in Live Queries](./guides/live-queries#using-with-react-suspense) for detailed usage patterns and when to use `useLiveSuspenseQuery` vs `useLiveQuery`.
341
342#### `queryBuilder`
343
344You can also build queries directly (outside of the component lifecycle) using the underlying `queryBuilder` API:
345
346```ts
347import { createLiveQueryCollection, eq } from "@tanstack/db"
348
349const completedTodos = createLiveQueryCollection({
350 startSync: true,
351 query: (q) =>
352 q
353 .from({ todo: todoCollection })
354 .where(({ todo }) => eq(todo.completed, true)),
355})
356
357const results = completedTodos.toArray
358```
359
360Note also that:
361
3621. the query results [are themselves a collection](#derived-collections)
3632. the `useLiveQuery` automatically starts and stops live query subscriptions when you mount and unmount your components; if you're creating queries manually, you need to manually manage the subscription lifecycle yourself
364
365See the [Live Queries](./guides/live-queries.md) documentation for more details.
366
367### Transactional mutators
368
369For more complex mutations beyond simple CRUD operations, TanStack DB provides `createOptimisticAction` and `createTransaction` for creating custom mutations with full control over the mutation lifecycle.
370
371See the [Mutations guide](./guides/mutations.md) for comprehensive documentation on:
372
373- Creating custom actions with `createOptimisticAction`
374- Manual transactions with `createTransaction`
375- Mutation merging behavior
376- Controlling optimistic vs non-optimistic updates
377- Handling temporary IDs
378- Transaction lifecycle states
379
380## Usage examples
381
382Here we illustrate two common ways of using TanStack DB:
383
3841. [using TanStack Query](#1-tanstack-query) with an existing REST API
3852. [using a sync engine](#2-sync-engine) for real-time sync with your backend
386
387> [!TIP]
388> You can combine these patterns. One of the benefits of TanStack DB is that you can integrate different ways of loading data and handling mutations into the same app. Your components don't need to know where the data came from or goes.
389
390### 1. TanStack Query
391
392You can use TanStack DB with your existing REST API via TanStack Query.
393
394The steps are to:
395
3961. create [QueryCollection](./collections/query-collection.md)s that load data using TanStack Query
3972. implement mutation handlers that handle mutations by posting them to your API endpoints
398
399```tsx
400import { useLiveQuery, createCollection } from "@tanstack/react-db"
401import { queryCollectionOptions } from "@tanstack/query-db-collection"
402
403// Load data into collections using TanStack Query.
404// It's common to define these in a `collections` module.
405const todoCollection = createCollection(
406 queryCollectionOptions({
407 queryKey: ["todos"],
408 queryFn: async () => fetch("/api/todos"),
409 getKey: (item) => item.id,
410 schema: todoSchema, // any standard schema
411 onInsert: async ({ transaction }) => {
412 const { changes: newTodo } = transaction.mutations[0]
413
414 // Handle the local write by sending it to your API.
415 await api.todos.create(newTodo)
416 },
417 // also add onUpdate, onDelete as needed.
418 })
419)
420const listCollection = createCollection(
421 queryCollectionOptions({
422 queryKey: ["todo-lists"],
423 queryFn: async () => fetch("/api/todo-lists"),
424 getKey: (item) => item.id,
425 schema: todoListSchema,
426 onInsert: async ({ transaction }) => {
427 const { changes: newTodo } = transaction.mutations[0]
428
429 // Handle the local write by sending it to your API.
430 await api.todoLists.create(newTodo)
431 },
432 // also add onUpdate, onDelete as needed.
433 })
434)
435
436const Todos = () => {
437 // Read the data using live queries. Here we show a live
438 // query that joins across two collections.
439 const { data: todos } = useLiveQuery((q) =>
440 q
441 .from({ todo: todoCollection })
442 .join(
443 { list: listCollection },
444 ({ todo, list }) => eq(list.id, todo.list_id),
445 "inner"
446 )
447 .where(({ list }) => eq(list.active, true))
448 .select(({ todo, list }) => ({
449 id: todo.id,
450 text: todo.text,
451 status: todo.status,
452 listName: list.name,
453 }))
454 )
455
456 // ...
457}
458```
459
460This pattern allows you to extend an existing TanStack Query application, or any application built on a REST API, with blazing fast, cross-collection live queries and local optimistic mutations with automatically managed optimistic state.
461
462### 2. Sync Engine
463
464One of the most powerful ways of using TanStack DB is with a sync engine, for a fully local-first experience with real-time sync. This allows you to incrementally adopt sync into an existing app, whilst still handling writes with your existing API.
465
466#### Why Sync Engines?
467
468While TanStack DB works great with REST APIs, sync engines provide powerful benefits:
469
470- **Easy real-time updates**: No WebSocket plumbing—write to your database and changes stream automatically to all clients
471- **Automatic side-effects**: When a mutation triggers cascading changes across tables, all affected data syncs automatically without manual cache invalidation
472- **Efficient delta updates**: Only changed rows cross the wire, making it practical to load large datasets client-side
473
474This pattern enables the "load everything once" approach that makes apps like Linear and Figma feel instant.
475
476Here, we illustrate this pattern using [ElectricSQL](https://electric-sql.com) as the sync engine, but this pattern also works with other sync engines like [PowerSync](https://www.powersync.com/?utm_source=tanstack&utm_campaign=tanstack_partner), [RxDB](https://rxdb.info/), and [TrailBase](https://trailbase.io/).
477
478```tsx
479import type { Collection } from "@tanstack/db"
480import type {
481 MutationFn,
482 PendingMutation,
483 createCollection,
484} from "@tanstack/react-db"
485import { electricCollectionOptions } from "@tanstack/electric-db-collection"
486
487export const todoCollection = createCollection(
488 electricCollectionOptions({
489 id: "todos",
490 schema: todoSchema,
491 // Electric syncs data using "shapes". These are filtered views
492 // on database tables that Electric keeps in sync for you.
493 shapeOptions: {
494 url: "https://api.electric-sql.cloud/v1/shape",
495 params: {
496 table: "todos",
497 },
498 },
499 getKey: (item) => item.id,
500 schema: todoSchema,
501 onInsert: async ({ transaction }) => {
502 const response = await api.todos.create(transaction.mutations[0].modified)
503
504 return { txid: response.txid }
505 },
506 // You can also implement onUpdate, onDelete as needed.
507 })
508)
509
510const AddTodo = () => {
511 return (
512 <Button
513 onClick={() => todoCollection.insert({ text: "🔥 Make app faster" })}
514 />
515 )
516}
517```
518
519## React Native
520
521When using TanStack DB with React Native, you need to install and configure a UUID generation library since React Native doesn't include crypto.randomUUID() by default.
522
523Install the `react-native-random-uuid` package:
524
525```bash
526npm install react-native-random-uuid
527```
528
529Then import it at the entry point of your React Native app (e.g., in your `App.js` or `index.js`):
530
531```javascript
532import "react-native-random-uuid"
533```
534
535This polyfill provides the `crypto.randomUUID()` function that TanStack DB uses internally for generating unique identifiers.
536
537## More info
538
539If you have questions / need help using TanStack DB, let us know on the Discord or start a GitHub discussion:
540
541- [`#db` channel in the TanStack discord](https://discord.gg/yjUNbvbraC)
542- [GitHub discussions](https://github.com/tanstack/db/discussions)