Open History to see the last commit
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 )
88}
89
90function App() {
91 return (
92 <Suspense fallback={<div>Loading...</div>}>
93 <TodoList />
94 </Suspense>
95 )
96}
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()
105)
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 )
127}
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!
140)
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>
150}
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 )
233}
234
235function App() {
236 return (
237 <Suspense fallback={<div>Loading...</div>}>
238 <TodoList />
239 </Suspense>
240 )
241}
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()
250)
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 )
272}
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!
285)
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>
295}
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 )
384}
385
386function App() {
387 return (
388 <Suspense fallback={<div>Loading...</div>}>
389 <TodoList />
390 </Suspense>
391 )
392}
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()
401)
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 )
423}
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!
436)
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>
446}
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 )
536}
537
538function App() {
539 return (
540 <Suspense fallback={<div>Loading...</div>}>
541 <TodoList />
542 </Suspense>
543 )
544}
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()
553)
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 )
575}
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!
588)
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>
598}
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 )
688}
689
690function App() {
691 return (
692 <Suspense fallback={<div>Loading...</div>}>
693 <TodoList />
694 </Suspense>
695 )
696}
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()
705)
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 )
727}
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!
740)
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>
750}
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```