Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

useLiveSuspenseQuery.md

759 lines15.9 KB

1---
2id: useLiveSuspenseQuery
3title: useLiveSuspenseQuery
4---
5​
6# Function: useLiveSuspenseQuery()
7​
8## Call Signature
9​
10```ts
11function useLiveSuspenseQuery<TContext>(queryFn, deps?): object;
12```
13​
14Defined in: [useLiveSuspenseQuery.ts:110](https://github.com/TanStack/db/blob/main/packages/react-db/src/useLiveSuspenseQuery.ts#L110)
15​
16Create a live query with React Suspense support
17​
18### Type Parameters
19​
20#### TContext
21​
22`TContext` *extends* `Context`
23​
24### Parameters
25​
26#### queryFn
27​
28(`q`) => `QueryBuilder`\<`TContext`\>
29​
30Query function that defines what data to fetch
31​
32#### deps?
33​
34`unknown`[]
35​
36Deprecated array of dependencies that trigger query re-execution when changed
37​
38### Returns
39​
40`object`
41​
42Object with reactive data and state - data is guaranteed to be defined
43​
44#### collection
45​
46```ts
47collection: Collection<{ [K in string | number | symbol]: ResultValue<TContext>[K] }, string | number, {
48}>;
49```
50​
51#### data
52​
53```ts
54data: InferResultType<TContext>;
55```
56​
57#### state
58​
59```ts
60state: Map<string | number, { [K in string | number | symbol]: ResultValue<TContext>[K] }>;
61```
62​
63### Throws
64​
65Promise when data is loading (caught by Suspense boundary)
66​
67### Throws
68​
69Error when collection fails (caught by Error boundary)
70​
71### Examples
72​
73```ts
74// Basic usage with Suspense
75function TodoList() {
76 const { data } = useLiveSuspenseQuery({
77 query: (q) =>
78 q.from({ todos: todosCollection })
79 .where(({ todos }) => eq(todos.completed, false))
80 .select(({ todos }) => ({ id: todos.id, text: todos.text }))
81 })
82​
83 return (
84 <ul>
85 {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
86 </ul>
87 )
89​
90function App() {
91 return (
92 <Suspense fallback={<div>Loading...</div>}>
93 <TodoList />
94 </Suspense>
95 )
97```
98​
99```ts
100// Single result query
101const { data } = useLiveSuspenseQuery(
102 (q) => q.from({ todos: todosCollection })
103 .where(({ todos }) => eq(todos.id, 1))
104 .findOne()
106// data is guaranteed to be the single item (or undefined if not found)
107```
108​
109```ts
110// Structured captured values are included in derived query identity and trigger re-suspension
111const { data } = useLiveSuspenseQuery({
112 query: (q) => q.from({ todos: todosCollection })
113 .where(({ todos }) => gt(todos.priority, minPriority)),
114})
115```
116​
117```ts
118// With Error boundary
119function App() {
120 return (
121 <ErrorBoundary fallback={<div>Error loading data</div>}>
122 <Suspense fallback={<div>Loading...</div>}>
123 <TodoList />
124 </Suspense>
125 </ErrorBoundary>
126 )
128```
129​
130### Remarks
131​
132**Important:** This hook does NOT support disabled queries (returning undefined/null).
133Following TanStack Query's useSuspenseQuery design, the query callback must always
134return a valid query, collection, or config object.
135​
136❌ **This will cause a type error:**
137```ts
138useLiveSuspenseQuery(
139 (q) => userId ? q.from({ users }) : undefined // ❌ Error!
141```
142​
143✅ **Use conditional rendering instead:**
144```ts
145function Profile({ userId }: { userId: string }) {
146 const { data } = useLiveSuspenseQuery({
147 query: (q) => q.from({ users }).where(({ users }) => eq(users.id, userId)),
148 })
149 return <div>{data.name}</div>
151​
152// In parent component:
153{userId ? <Profile userId={userId} /> : <div>No user</div>}
154```
155​
156✅ **For optional inputs, conditionally render a component with complete query inputs:**
157```ts
158{userId ? <Profile userId={userId} /> : <div>No user</div>}
159```
160​
161## Call Signature
162​
163```ts
164function useLiveSuspenseQuery<TContext>(config): object;
165```
166​
167Defined in: [useLiveSuspenseQuery.ts:120](https://github.com/TanStack/db/blob/main/packages/react-db/src/useLiveSuspenseQuery.ts#L120)
168​
169Create a live query with React Suspense support
170​
171### Type Parameters
172​
173#### TContext
174​
175`TContext` *extends* `Context`
176​
177### Parameters
178​
179#### config
180​
181[`UseLiveQueryConfig`](../type-aliases/UseLiveQueryConfig.md)\<`TContext`\>
182​
183### Returns
184​
185`object`
186​
187Object with reactive data and state - data is guaranteed to be defined
188​
189#### collection
190​
191```ts
192collection: Collection<{ [K in string | number | symbol]: ResultValue<TContext>[K] }, string | number, {
193}>;
194```
195​
196#### data
197​
198```ts
199data: InferResultType<TContext>;
200```
201​
202#### state
203​
204```ts
205state: Map<string | number, { [K in string | number | symbol]: ResultValue<TContext>[K] }>;
206```
207​
208### Throws
209​
210Promise when data is loading (caught by Suspense boundary)
211​
212### Throws
213​
214Error when collection fails (caught by Error boundary)
215​
216### Examples
217​
218```ts
219// Basic usage with Suspense
220function TodoList() {
221 const { data } = useLiveSuspenseQuery({
222 query: (q) =>
223 q.from({ todos: todosCollection })
224 .where(({ todos }) => eq(todos.completed, false))
225 .select(({ todos }) => ({ id: todos.id, text: todos.text }))
226 })
227​
228 return (
229 <ul>
230 {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
231 </ul>
232 )
234​
235function App() {
236 return (
237 <Suspense fallback={<div>Loading...</div>}>
238 <TodoList />
239 </Suspense>
240 )
242```
243​
244```ts
245// Single result query
246const { data } = useLiveSuspenseQuery(
247 (q) => q.from({ todos: todosCollection })
248 .where(({ todos }) => eq(todos.id, 1))
249 .findOne()
251// data is guaranteed to be the single item (or undefined if not found)
252```
253​
254```ts
255// Structured captured values are included in derived query identity and trigger re-suspension
256const { data } = useLiveSuspenseQuery({
257 query: (q) => q.from({ todos: todosCollection })
258 .where(({ todos }) => gt(todos.priority, minPriority)),
259})
260```
261​
262```ts
263// With Error boundary
264function App() {
265 return (
266 <ErrorBoundary fallback={<div>Error loading data</div>}>
267 <Suspense fallback={<div>Loading...</div>}>
268 <TodoList />
269 </Suspense>
270 </ErrorBoundary>
271 )
273```
274​
275### Remarks
276​
277**Important:** This hook does NOT support disabled queries (returning undefined/null).
278Following TanStack Query's useSuspenseQuery design, the query callback must always
279return a valid query, collection, or config object.
280​
281❌ **This will cause a type error:**
282```ts
283useLiveSuspenseQuery(
284 (q) => userId ? q.from({ users }) : undefined // ❌ Error!
286```
287​
288✅ **Use conditional rendering instead:**
289```ts
290function Profile({ userId }: { userId: string }) {
291 const { data } = useLiveSuspenseQuery({
292 query: (q) => q.from({ users }).where(({ users }) => eq(users.id, userId)),
293 })
294 return <div>{data.name}</div>
296​
297// In parent component:
298{userId ? <Profile userId={userId} /> : <div>No user</div>}
299```
300​
301✅ **For optional inputs, conditionally render a component with complete query inputs:**
302```ts
303{userId ? <Profile userId={userId} /> : <div>No user</div>}
304```
305​
306## Call Signature
307​
308```ts
309function useLiveSuspenseQuery<TContext>(config, deps?): object;
310```
311​
312Defined in: [useLiveSuspenseQuery.ts:129](https://github.com/TanStack/db/blob/main/packages/react-db/src/useLiveSuspenseQuery.ts#L129)
313​
314Create a live query with React Suspense support
315​
316### Type Parameters
317​
318#### TContext
319​
320`TContext` *extends* `Context`
321​
322### Parameters
323​
324#### config
325​
326`LiveQueryCollectionConfig`\<`TContext`\>
327​
328#### deps?
329​
330`unknown`[]
331​
332Deprecated array of dependencies that trigger query re-execution when changed
333​
334### Returns
335​
336`object`
337​
338Object with reactive data and state - data is guaranteed to be defined
339​
340#### collection
341​
342```ts
343collection: Collection<{ [K in string | number | symbol]: ResultValue<TContext>[K] }, string | number, {
344}>;
345```
346​
347#### data
348​
349```ts
350data: InferResultType<TContext>;
351```
352​
353#### state
354​
355```ts
356state: Map<string | number, { [K in string | number | symbol]: ResultValue<TContext>[K] }>;
357```
358​
359### Throws
360​
361Promise when data is loading (caught by Suspense boundary)
362​
363### Throws
364​
365Error when collection fails (caught by Error boundary)
366​
367### Examples
368​
369```ts
370// Basic usage with Suspense
371function TodoList() {
372 const { data } = useLiveSuspenseQuery({
373 query: (q) =>
374 q.from({ todos: todosCollection })
375 .where(({ todos }) => eq(todos.completed, false))
376 .select(({ todos }) => ({ id: todos.id, text: todos.text }))
377 })
378​
379 return (
380 <ul>
381 {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
382 </ul>
383 )
385​
386function App() {
387 return (
388 <Suspense fallback={<div>Loading...</div>}>
389 <TodoList />
390 </Suspense>
391 )
393```
394​
395```ts
396// Single result query
397const { data } = useLiveSuspenseQuery(
398 (q) => q.from({ todos: todosCollection })
399 .where(({ todos }) => eq(todos.id, 1))
400 .findOne()
402// data is guaranteed to be the single item (or undefined if not found)
403```
404​
405```ts
406// Structured captured values are included in derived query identity and trigger re-suspension
407const { data } = useLiveSuspenseQuery({
408 query: (q) => q.from({ todos: todosCollection })
409 .where(({ todos }) => gt(todos.priority, minPriority)),
410})
411```
412​
413```ts
414// With Error boundary
415function App() {
416 return (
417 <ErrorBoundary fallback={<div>Error loading data</div>}>
418 <Suspense fallback={<div>Loading...</div>}>
419 <TodoList />
420 </Suspense>
421 </ErrorBoundary>
422 )
424```
425​
426### Remarks
427​
428**Important:** This hook does NOT support disabled queries (returning undefined/null).
429Following TanStack Query's useSuspenseQuery design, the query callback must always
430return a valid query, collection, or config object.
431​
432❌ **This will cause a type error:**
433```ts
434useLiveSuspenseQuery(
435 (q) => userId ? q.from({ users }) : undefined // ❌ Error!
437```
438​
439✅ **Use conditional rendering instead:**
440```ts
441function Profile({ userId }: { userId: string }) {
442 const { data } = useLiveSuspenseQuery({
443 query: (q) => q.from({ users }).where(({ users }) => eq(users.id, userId)),
444 })
445 return <div>{data.name}</div>
447​
448// In parent component:
449{userId ? <Profile userId={userId} /> : <div>No user</div>}
450```
451​
452✅ **For optional inputs, conditionally render a component with complete query inputs:**
453```ts
454{userId ? <Profile userId={userId} /> : <div>No user</div>}
455```
456​
457## Call Signature
458​
459```ts
460function useLiveSuspenseQuery<TResult, TKey, TUtils>(liveQueryCollection): object;
461```
462​
463Defined in: [useLiveSuspenseQuery.ts:139](https://github.com/TanStack/db/blob/main/packages/react-db/src/useLiveSuspenseQuery.ts#L139)
464​
465Create a live query with React Suspense support
466​
467### Type Parameters
468​
469#### TResult
470​
471`TResult` *extends* `object`
472​
473#### TKey
474​
475`TKey` *extends* `string` \| `number`
476​
477#### TUtils
478​
479`TUtils` *extends* `Record`\<`string`, `any`\>
480​
481### Parameters
482​
483#### liveQueryCollection
484​
485`Collection`\<`TResult`, `TKey`, `TUtils`, `StandardSchemaV1`\<`unknown`, `unknown`\>, `TResult`\> & `NonSingleResult`
486​
487### Returns
488​
489`object`
490​
491Object with reactive data and state - data is guaranteed to be defined
492​
493#### collection
494​
495```ts
496collection: Collection<TResult, TKey, TUtils>;
497```
498​
499#### data
500​
501```ts
502data: TResult[];
503```
504​
505#### state
506​
507```ts
508state: Map<TKey, TResult>;
509```
510​
511### Throws
512​
513Promise when data is loading (caught by Suspense boundary)
514​
515### Throws
516​
517Error when collection fails (caught by Error boundary)
518​
519### Examples
520​
521```ts
522// Basic usage with Suspense
523function TodoList() {
524 const { data } = useLiveSuspenseQuery({
525 query: (q) =>
526 q.from({ todos: todosCollection })
527 .where(({ todos }) => eq(todos.completed, false))
528 .select(({ todos }) => ({ id: todos.id, text: todos.text }))
529 })
530​
531 return (
532 <ul>
533 {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
534 </ul>
535 )
537​
538function App() {
539 return (
540 <Suspense fallback={<div>Loading...</div>}>
541 <TodoList />
542 </Suspense>
543 )
545```
546​
547```ts
548// Single result query
549const { data } = useLiveSuspenseQuery(
550 (q) => q.from({ todos: todosCollection })
551 .where(({ todos }) => eq(todos.id, 1))
552 .findOne()
554// data is guaranteed to be the single item (or undefined if not found)
555```
556​
557```ts
558// Structured captured values are included in derived query identity and trigger re-suspension
559const { data } = useLiveSuspenseQuery({
560 query: (q) => q.from({ todos: todosCollection })
561 .where(({ todos }) => gt(todos.priority, minPriority)),
562})
563```
564​
565```ts
566// With Error boundary
567function App() {
568 return (
569 <ErrorBoundary fallback={<div>Error loading data</div>}>
570 <Suspense fallback={<div>Loading...</div>}>
571 <TodoList />
572 </Suspense>
573 </ErrorBoundary>
574 )
576```
577​
578### Remarks
579​
580**Important:** This hook does NOT support disabled queries (returning undefined/null).
581Following TanStack Query's useSuspenseQuery design, the query callback must always
582return a valid query, collection, or config object.
583​
584❌ **This will cause a type error:**
585```ts
586useLiveSuspenseQuery(
587 (q) => userId ? q.from({ users }) : undefined // ❌ Error!
589```
590​
591✅ **Use conditional rendering instead:**
592```ts
593function Profile({ userId }: { userId: string }) {
594 const { data } = useLiveSuspenseQuery({
595 query: (q) => q.from({ users }).where(({ users }) => eq(users.id, userId)),
596 })
597 return <div>{data.name}</div>
599​
600// In parent component:
601{userId ? <Profile userId={userId} /> : <div>No user</div>}
602```
603​
604✅ **For optional inputs, conditionally render a component with complete query inputs:**
605```ts
606{userId ? <Profile userId={userId} /> : <div>No user</div>}
607```
608​
609## Call Signature
610​
611```ts
612function useLiveSuspenseQuery<TResult, TKey, TUtils>(liveQueryCollection): object;
613```
614​
615Defined in: [useLiveSuspenseQuery.ts:152](https://github.com/TanStack/db/blob/main/packages/react-db/src/useLiveSuspenseQuery.ts#L152)
616​
617Create a live query with React Suspense support
618​
619### Type Parameters
620​
621#### TResult
622​
623`TResult` *extends* `object`
624​
625#### TKey
626​
627`TKey` *extends* `string` \| `number`
628​
629#### TUtils
630​
631`TUtils` *extends* `Record`\<`string`, `any`\>
632​
633### Parameters
634​
635#### liveQueryCollection
636​
637`Collection`\<`TResult`, `TKey`, `TUtils`, `StandardSchemaV1`\<`unknown`, `unknown`\>, `TResult`\> & `SingleResult`
638​
639### Returns
640​
641`object`
642​
643Object with reactive data and state - data is guaranteed to be defined
644​
645#### collection
646​
647```ts
648collection: Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult> & SingleResult;
649```
650​
651#### data
652​
653```ts
654data: TResult | undefined;
655```
656​
657#### state
658​
659```ts
660state: Map<TKey, TResult>;
661```
662​
663### Throws
664​
665Promise when data is loading (caught by Suspense boundary)
666​
667### Throws
668​
669Error when collection fails (caught by Error boundary)
670​
671### Examples
672​
673```ts
674// Basic usage with Suspense
675function TodoList() {
676 const { data } = useLiveSuspenseQuery({
677 query: (q) =>
678 q.from({ todos: todosCollection })
679 .where(({ todos }) => eq(todos.completed, false))
680 .select(({ todos }) => ({ id: todos.id, text: todos.text }))
681 })
682​
683 return (
684 <ul>
685 {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
686 </ul>
687 )
689​
690function App() {
691 return (
692 <Suspense fallback={<div>Loading...</div>}>
693 <TodoList />
694 </Suspense>
695 )
697```
698​
699```ts
700// Single result query
701const { data } = useLiveSuspenseQuery(
702 (q) => q.from({ todos: todosCollection })
703 .where(({ todos }) => eq(todos.id, 1))
704 .findOne()
706// data is guaranteed to be the single item (or undefined if not found)
707```
708​
709```ts
710// Structured captured values are included in derived query identity and trigger re-suspension
711const { data } = useLiveSuspenseQuery({
712 query: (q) => q.from({ todos: todosCollection })
713 .where(({ todos }) => gt(todos.priority, minPriority)),
714})
715```
716​
717```ts
718// With Error boundary
719function App() {
720 return (
721 <ErrorBoundary fallback={<div>Error loading data</div>}>
722 <Suspense fallback={<div>Loading...</div>}>
723 <TodoList />
724 </Suspense>
725 </ErrorBoundary>
726 )
728```
729​
730### Remarks
731​
732**Important:** This hook does NOT support disabled queries (returning undefined/null).
733Following TanStack Query's useSuspenseQuery design, the query callback must always
734return a valid query, collection, or config object.
735​
736❌ **This will cause a type error:**
737```ts
738useLiveSuspenseQuery(
739 (q) => userId ? q.from({ users }) : undefined // ❌ Error!
741```
742​
743✅ **Use conditional rendering instead:**
744```ts
745function Profile({ userId }: { userId: string }) {
746 const { data } = useLiveSuspenseQuery({
747 query: (q) => q.from({ users }).where(({ users }) => eq(users.id, userId)),
748 })
749 return <div>{data.name}</div>
751​
752// In parent component:
753{userId ? <Profile userId={userId} /> : <div>No user</div>}
754```
755​
756✅ **For optional inputs, conditionally render a component with complete query inputs:**
757```ts
758{userId ? <Profile userId={userId} /> : <div>No user</div>}
759```