Open History to see the last commit
1---
2id: useLiveQuery
3title: useLiveQuery
4---
5
6# Function: useLiveQuery()
7
8## Call Signature
9
10```ts
11function useLiveQuery<TContext>(queryFn, deps?): UseLiveQueryReturn<TContext>;
12```
13
14Defined in: [useLiveQuery.ts:138](https://github.com/TanStack/db/blob/main/packages/vue-db/src/useLiveQuery.ts#L138)
15
16Create a live query using a query function
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
36Array of reactive dependencies that trigger query re-execution when changed
37
38### Returns
39
40[`UseLiveQueryReturn`](../interfaces/UseLiveQueryReturn.md)\<`TContext`\>
41
42Reactive object with query data, state, and status information
43
44### Examples
45
46```ts
47// Basic query with object syntax
48const { data, isLoading } = useLiveQuery((q) =>
49 q.from({ todos: todosCollection })
50 .where(({ todos }) => eq(todos.completed, false))
51 .select(({ todos }) => ({ id: todos.id, text: todos.text }))
52)
53```
54
55```ts
56// With reactive dependencies
57const minPriority = ref(5)
58const { data, state } = useLiveQuery(
59 (q) => q.from({ todos: todosCollection })
60 .where(({ todos }) => gt(todos.priority, minPriority.value)),
61 [minPriority] // Re-run when minPriority changes
62)
63```
64
65```ts
66// Join pattern
67const { data } = useLiveQuery((q) =>
68 q.from({ issues: issueCollection })
69 .join({ persons: personCollection }, ({ issues, persons }) =>
70 eq(issues.userId, persons.id)
71 )
72 .select(({ issues, persons }) => ({
73 id: issues.id,
74 title: issues.title,
75 userName: persons.name
76 }))
77)
78```
79
80```ts
81// Handle loading and error states in template
82const { data, isLoading, isError, status } = useLiveQuery((q) =>
83 q.from({ todos: todoCollection })
84)
85
86// In template:
87// <div v-if="isLoading">Loading...</div>
88// <div v-else-if="isError">Error: {{ status }}</div>
89// <ul v-else>
90// <li v-for="todo in data" :key="todo.id">{{ todo.text }}</li>
91// </ul>
92```
93
94## Call Signature
95
96```ts
97function useLiveQuery<TContext>(queryFn, deps?): UseLiveQueryReturn<TContext>;
98```
99
100Defined in: [useLiveQuery.ts:144](https://github.com/TanStack/db/blob/main/packages/vue-db/src/useLiveQuery.ts#L144)
101
102Create a live query using a query function
103
104### Type Parameters
105
106#### TContext
107
108`TContext` *extends* `Context`
109
110### Parameters
111
112#### queryFn
113
114(`q`) => `QueryBuilder`\<`TContext`\> \| `null` \| `undefined`
115
116Query function that defines what data to fetch
117
118#### deps?
119
120`unknown`[]
121
122Array of reactive dependencies that trigger query re-execution when changed
123
124### Returns
125
126[`UseLiveQueryReturn`](../interfaces/UseLiveQueryReturn.md)\<`TContext`\>
127
128Reactive object with query data, state, and status information
129
130### Examples
131
132```ts
133// Basic query with object syntax
134const { data, isLoading } = useLiveQuery((q) =>
135 q.from({ todos: todosCollection })
136 .where(({ todos }) => eq(todos.completed, false))
137 .select(({ todos }) => ({ id: todos.id, text: todos.text }))
138)
139```
140
141```ts
142// With reactive dependencies
143const minPriority = ref(5)
144const { data, state } = useLiveQuery(
145 (q) => q.from({ todos: todosCollection })
146 .where(({ todos }) => gt(todos.priority, minPriority.value)),
147 [minPriority] // Re-run when minPriority changes
148)
149```
150
151```ts
152// Join pattern
153const { data } = useLiveQuery((q) =>
154 q.from({ issues: issueCollection })
155 .join({ persons: personCollection }, ({ issues, persons }) =>
156 eq(issues.userId, persons.id)
157 )
158 .select(({ issues, persons }) => ({
159 id: issues.id,
160 title: issues.title,
161 userName: persons.name
162 }))
163)
164```
165
166```ts
167// Handle loading and error states in template
168const { data, isLoading, isError, status } = useLiveQuery((q) =>
169 q.from({ todos: todoCollection })
170)
171
172// In template:
173// <div v-if="isLoading">Loading...</div>
174// <div v-else-if="isError">Error: {{ status }}</div>
175// <ul v-else>
176// <li v-for="todo in data" :key="todo.id">{{ todo.text }}</li>
177// </ul>
178```
179
180## Call Signature
181
182```ts
183function useLiveQuery<TContext>(config, deps?): UseLiveQueryReturn<TContext>;
184```
185
186Defined in: [useLiveQuery.ts:184](https://github.com/TanStack/db/blob/main/packages/vue-db/src/useLiveQuery.ts#L184)
187
188Create a live query using configuration object
189
190### Type Parameters
191
192#### TContext
193
194`TContext` *extends* `Context`
195
196### Parameters
197
198#### config
199
200`LiveQueryCollectionConfig`\<`TContext`\>
201
202Configuration object with query and options
203
204#### deps?
205
206`unknown`[]
207
208Array of reactive dependencies that trigger query re-execution when changed
209
210### Returns
211
212[`UseLiveQueryReturn`](../interfaces/UseLiveQueryReturn.md)\<`TContext`\>
213
214Reactive object with query data, state, and status information
215
216### Examples
217
218```ts
219// Basic config object usage
220const { data, status } = useLiveQuery({
221 query: (q) => q.from({ todos: todosCollection }),
222 gcTime: 60000
223})
224```
225
226```ts
227// With reactive dependencies
228const filter = ref('active')
229const { data, isReady } = useLiveQuery({
230 query: (q) => q.from({ todos: todosCollection })
231 .where(({ todos }) => eq(todos.status, filter.value))
232}, [filter])
233```
234
235```ts
236// Handle all states uniformly
237const { data, isLoading, isReady, isError } = useLiveQuery({
238 query: (q) => q.from({ items: itemCollection })
239})
240
241// In template:
242// <div v-if="isLoading">Loading...</div>
243// <div v-else-if="isError">Something went wrong</div>
244// <div v-else-if="!isReady">Preparing...</div>
245// <div v-else>{{ data.length }} items loaded</div>
246```
247
248## Call Signature
249
250```ts
251function useLiveQuery<TResult, TKey, TUtils>(liveQueryCollection): UseLiveQueryReturnWithCollection<TResult, TKey, TUtils>;
252```
253
254Defined in: [useLiveQuery.ts:229](https://github.com/TanStack/db/blob/main/packages/vue-db/src/useLiveQuery.ts#L229)
255
256Subscribe to an existing query collection (can be reactive)
257
258### Type Parameters
259
260#### TResult
261
262`TResult` *extends* `object`
263
264#### TKey
265
266`TKey` *extends* `string` \| `number`
267
268#### TUtils
269
270`TUtils` *extends* `Record`\<`string`, `any`\>
271
272### Parameters
273
274#### liveQueryCollection
275
276`MaybeRefOrGetter`\<`Collection`\<`TResult`, `TKey`, `TUtils`, `StandardSchemaV1`\<`unknown`, `unknown`\>, `TResult`\> & `NonSingleResult`\>
277
278Pre-created query collection to subscribe to (can be a ref)
279
280### Returns
281
282[`UseLiveQueryReturnWithCollection`](../interfaces/UseLiveQueryReturnWithCollection.md)\<`TResult`, `TKey`, `TUtils`\>
283
284Reactive object with query data, state, and status information
285
286### Examples
287
288```ts
289// Using pre-created query collection
290const myLiveQuery = createLiveQueryCollection((q) =>
291 q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))
292)
293const { data, collection } = useLiveQuery(myLiveQuery)
294```
295
296```ts
297// Reactive query collection reference
298const selectedQuery = ref(todosQuery)
299const { data, collection } = useLiveQuery(selectedQuery)
300
301// Switch queries reactively
302selectedQuery.value = archiveQuery
303```
304
305```ts
306// Access query collection methods directly
307const { data, collection, isReady } = useLiveQuery(existingQuery)
308
309// Use underlying collection for mutations
310const handleToggle = (id) => {
311 collection.value.update(id, draft => { draft.completed = !draft.completed })
312}
313```
314
315```ts
316// Handle states consistently
317const { data, isLoading, isError } = useLiveQuery(sharedQuery)
318
319// In template:
320// <div v-if="isLoading">Loading...</div>
321// <div v-else-if="isError">Error loading data</div>
322// <div v-else>
323// <Item v-for="item in data" :key="item.id" v-bind="item" />
324// </div>
325```
326
327## Call Signature
328
329```ts
330function useLiveQuery<TResult, TKey, TUtils>(liveQueryCollection): UseLiveQueryReturnWithSingleResultCollection<TResult, TKey, TUtils>;
331```
332
333Defined in: [useLiveQuery.ts:240](https://github.com/TanStack/db/blob/main/packages/vue-db/src/useLiveQuery.ts#L240)
334
335Create a live query using a query function
336
337### Type Parameters
338
339#### TResult
340
341`TResult` *extends* `object`
342
343#### TKey
344
345`TKey` *extends* `string` \| `number`
346
347#### TUtils
348
349`TUtils` *extends* `Record`\<`string`, `any`\>
350
351### Parameters
352
353#### liveQueryCollection
354
355`MaybeRefOrGetter`\<`Collection`\<`TResult`, `TKey`, `TUtils`, `StandardSchemaV1`\<`unknown`, `unknown`\>, `TResult`\> & `SingleResult`\>
356
357### Returns
358
359[`UseLiveQueryReturnWithSingleResultCollection`](../interfaces/UseLiveQueryReturnWithSingleResultCollection.md)\<`TResult`, `TKey`, `TUtils`\>
360
361Reactive object with query data, state, and status information
362
363### Examples
364
365```ts
366// Basic query with object syntax
367const { data, isLoading } = useLiveQuery((q) =>
368 q.from({ todos: todosCollection })
369 .where(({ todos }) => eq(todos.completed, false))
370 .select(({ todos }) => ({ id: todos.id, text: todos.text }))
371)
372```
373
374```ts
375// With reactive dependencies
376const minPriority = ref(5)
377const { data, state } = useLiveQuery(
378 (q) => q.from({ todos: todosCollection })
379 .where(({ todos }) => gt(todos.priority, minPriority.value)),
380 [minPriority] // Re-run when minPriority changes
381)
382```
383
384```ts
385// Join pattern
386const { data } = useLiveQuery((q) =>
387 q.from({ issues: issueCollection })
388 .join({ persons: personCollection }, ({ issues, persons }) =>
389 eq(issues.userId, persons.id)
390 )
391 .select(({ issues, persons }) => ({
392 id: issues.id,
393 title: issues.title,
394 userName: persons.name
395 }))
396)
397```
398
399```ts
400// Handle loading and error states in template
401const { data, isLoading, isError, status } = useLiveQuery((q) =>
402 q.from({ todos: todoCollection })
403)
404
405// In template:
406// <div v-if="isLoading">Loading...</div>
407// <div v-else-if="isError">Error: {{ status }}</div>
408// <ul v-else>
409// <li v-for="todo in data" :key="todo.id">{{ todo.text }}</li>
410// </ul>
411```