@@ -11,7 +11,7 @@ title: useLiveSuspenseQuery
1111function useLiveSuspenseQuery<TContext >(queryFn , deps ? ): object ;
1212```
1313
14- Defined in: [ useLiveSuspenseQuery.ts:76 ] ( https://github.com/TanStack/db/blob/main/packages/react-db/src/useLiveSuspenseQuery.ts#L76 )
14+ Defined in: [ useLiveSuspenseQuery.ts:109 ] ( https://github.com/TanStack/db/blob/main/packages/react-db/src/useLiveSuspenseQuery.ts#L109 )
1515
1616Create a live query with React Suspense support
1717
@@ -127,13 +127,47 @@ function App() {
127127}
128128```
129129
130+ ### Remarks
131+
132+ ** Important:** This hook does NOT support disabled queries (returning undefined/null).
133+ Following TanStack Query's useSuspenseQuery design, the query callback must always
134+ return a valid query, collection, or config object.
135+
136+ ❌ ** This will cause a type error:**
137+ ``` ts
138+ useLiveSuspenseQuery (
139+ (q ) => userId ? q .from ({ users }) : undefined // ❌ Error!
140+ )
141+ ```
142+
143+ ✅ ** Use conditional rendering instead:**
144+ ``` ts
145+ function Profile({ userId }: { userId: string }) {
146+ const { data } = useLiveSuspenseQuery (
147+ (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+ ✅ ** Or use useLiveQuery for conditional queries:**
157+ ``` ts
158+ const { data, isEnabled } = useLiveQuery (
159+ (q ) => userId ? q .from ({ users }) : undefined , // ✅ Supported!
160+ [userId ]
161+ )
162+ ```
163+
130164## Call Signature
131165
132166``` ts
133167function useLiveSuspenseQuery<TContext >(config , deps ? ): object ;
134168```
135169
136- Defined in: [ useLiveSuspenseQuery.ts:86 ] ( https://github.com/TanStack/db/blob/main/packages/react-db/src/useLiveSuspenseQuery.ts#L86 )
170+ Defined in: [ useLiveSuspenseQuery.ts:119 ] ( https://github.com/TanStack/db/blob/main/packages/react-db/src/useLiveSuspenseQuery.ts#L119 )
137171
138172Create a live query with React Suspense support
139173
@@ -247,13 +281,47 @@ function App() {
247281}
248282```
249283
284+ ### Remarks
285+
286+ ** Important:** This hook does NOT support disabled queries (returning undefined/null).
287+ Following TanStack Query's useSuspenseQuery design, the query callback must always
288+ return a valid query, collection, or config object.
289+
290+ ❌ ** This will cause a type error:**
291+ ``` ts
292+ useLiveSuspenseQuery (
293+ (q ) => userId ? q .from ({ users }) : undefined // ❌ Error!
294+ )
295+ ```
296+
297+ ✅ ** Use conditional rendering instead:**
298+ ``` ts
299+ function Profile({ userId }: { userId: string }) {
300+ const { data } = useLiveSuspenseQuery (
301+ (q ) => q .from ({ users }).where (({ users }) => eq (users .id , userId ))
302+ )
303+ return <div >{data.name }< / div >
304+ }
305+
306+ // In parent component:
307+ {userId ? <Profile userId ={userId} /> : <div >No user < / div > }
308+ ```
309+
310+ ✅ ** Or use useLiveQuery for conditional queries:**
311+ ``` ts
312+ const { data, isEnabled } = useLiveQuery (
313+ (q ) => userId ? q .from ({ users }) : undefined , // ✅ Supported!
314+ [userId ]
315+ )
316+ ```
317+
250318## Call Signature
251319
252320``` ts
253321function useLiveSuspenseQuery<TResult , TKey , TUtils >(liveQueryCollection ): object ;
254322```
255323
256- Defined in: [ useLiveSuspenseQuery.ts:96 ] ( https://github.com/TanStack/db/blob/main/packages/react-db/src/useLiveSuspenseQuery.ts#L96 )
324+ Defined in: [ useLiveSuspenseQuery.ts:129 ] ( https://github.com/TanStack/db/blob/main/packages/react-db/src/useLiveSuspenseQuery.ts#L129 )
257325
258326Create a live query with React Suspense support
259327
@@ -368,13 +436,47 @@ function App() {
368436}
369437```
370438
439+ ### Remarks
440+
441+ ** Important:** This hook does NOT support disabled queries (returning undefined/null).
442+ Following TanStack Query's useSuspenseQuery design, the query callback must always
443+ return a valid query, collection, or config object.
444+
445+ ❌ ** This will cause a type error:**
446+ ``` ts
447+ useLiveSuspenseQuery (
448+ (q ) => userId ? q .from ({ users }) : undefined // ❌ Error!
449+ )
450+ ```
451+
452+ ✅ ** Use conditional rendering instead:**
453+ ``` ts
454+ function Profile({ userId }: { userId: string }) {
455+ const { data } = useLiveSuspenseQuery (
456+ (q ) => q .from ({ users }).where (({ users }) => eq (users .id , userId ))
457+ )
458+ return <div >{data.name }< / div >
459+ }
460+
461+ // In parent component:
462+ {userId ? <Profile userId ={userId} /> : <div >No user < / div > }
463+ ```
464+
465+ ✅ ** Or use useLiveQuery for conditional queries:**
466+ ``` ts
467+ const { data, isEnabled } = useLiveQuery (
468+ (q ) => userId ? q .from ({ users }) : undefined , // ✅ Supported!
469+ [userId ]
470+ )
471+ ```
472+
371473## Call Signature
372474
373475``` ts
374476function useLiveSuspenseQuery<TResult , TKey , TUtils >(liveQueryCollection ): object ;
375477```
376478
377- Defined in: [ useLiveSuspenseQuery.ts:109 ] ( https://github.com/TanStack/db/blob/main/packages/react-db/src/useLiveSuspenseQuery.ts#L109 )
479+ Defined in: [ useLiveSuspenseQuery.ts:142 ] ( https://github.com/TanStack/db/blob/main/packages/react-db/src/useLiveSuspenseQuery.ts#L142 )
378480
379481Create a live query with React Suspense support
380482
@@ -488,3 +590,37 @@ function App() {
488590 )
489591}
490592```
593+
594+ ### Remarks
595+
596+ ** Important:** This hook does NOT support disabled queries (returning undefined/null).
597+ Following TanStack Query's useSuspenseQuery design, the query callback must always
598+ return a valid query, collection, or config object.
599+
600+ ❌ ** This will cause a type error:**
601+ ``` ts
602+ useLiveSuspenseQuery (
603+ (q ) => userId ? q .from ({ users }) : undefined // ❌ Error!
604+ )
605+ ```
606+
607+ ✅ ** Use conditional rendering instead:**
608+ ``` ts
609+ function Profile({ userId }: { userId: string }) {
610+ const { data } = useLiveSuspenseQuery (
611+ (q ) => q .from ({ users }).where (({ users }) => eq (users .id , userId ))
612+ )
613+ return <div >{data.name }< / div >
614+ }
615+
616+ // In parent component:
617+ {userId ? <Profile userId ={userId} /> : <div >No user < / div > }
618+ ```
619+
620+ ✅ ** Or use useLiveQuery for conditional queries:**
621+ ``` ts
622+ const { data, isEnabled } = useLiveQuery (
623+ (q ) => userId ? q .from ({ users }) : undefined , // ✅ Supported!
624+ [userId ]
625+ )
626+ ```
0 commit comments