Open History to see the last commit
1---
2id: useQuery
3title: useQuery
4redirect_from:
5 - framework/vue/reference/useQuery
6---
7β
8<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
9β
10## Overview
11β
12```ts
13function useQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseQueryDefinedReturnType<TData, TError>;
14function useQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseQueryReturnType<TData, TError>;
15function useQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: MaybeRefOrGetter<UseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>>, queryClient?: QueryClient): UseQueryReturnType<TData, TError>;
16```
17β
18- [`DefinedInitialQueryOptions` β `UseQueryDefinedReturnType`](#call-signature-1): This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`).
19- [`UndefinedInitialQueryOptions` β `UseQueryReturnType`](#call-signature-2): `enabled` tracks reactive dependencies automatically as a `ref`, a plain value, or a reactive getter (`() => ...`). `queryKey` reacts through a `ref` or a reactive getter for the array itself, or `ref`s and reactive getters as individual entries. Other options are read once when passed as a plain value, and stay reactive when passed as a `ref` or a `computed`.
20- [`MaybeRefOrGetter` β `UseQueryReturnType`](#call-signature-3): Fallback overload for options whose `initialData` presence isn't statically known β for example, a `ref`/reactive object built up conditionally, rather than a plain object literal. Prefer one of the other overloads when possible, since they infer whether `data` can be `undefined` from `initialData` directly.
21β
22See also: [Parameters](#parameters-summary) Β· [Returns](#returns-summary)
23β
24<a id="call-signature-1"></a>
25β
26## Call Signature
27β
28```ts
29function useQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseQueryDefinedReturnType<TData, TError>;
30```
31β
32Defined in: [packages/vue-query/src/useQuery.ts:73](https://github.com/TanStack/query/blob/main/packages/vue-query/src/useQuery.ts#L73)
33β
34This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless
35a `select` changes `TData` to include `undefined`).
36β
37`enabled` tracks reactive dependencies automatically as a `ref`, a plain value, or a reactive getter
38(`() => ...`). `queryKey` reacts through a `ref` or a reactive getter for the array itself, or `ref`s and
39reactive getters as individual entries. Other options are read once when passed as a plain value, and stay
40reactive when passed as a `ref` or a `computed`.
41β
42### Type Parameters
43β
44#### TQueryFnData
45β
46`TQueryFnData` = `unknown`
47β
48#### TError
49β
50`TError` = `Error`
51β
52#### TData
53β
54`TData` = `TQueryFnData`
55β
56#### TQueryKey
57β
58`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
59β
60### Parameters
61β
62#### options
63β
64[`DefinedInitialQueryOptions`](../type-aliases/DefinedInitialQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
65β
66The [DefinedInitialQueryOptions](../type-aliases/DefinedInitialQueryOptions.md) to use β everything you can pass to `useQuery`, with
67`initialData` set.
68β
69#### queryClient?
70β
71[`QueryClient`](../classes/QueryClient.md)
72β
73Use this to use a custom `QueryClient`. Otherwise, the one provided by `VueQueryPlugin`
74will be used.
75β
76### Returns
77β
78[`UseQueryDefinedReturnType`](../type-aliases/UseQueryDefinedReturnType.md)\<`TData`, `TError`\>
79β
80The current query result, typed so that `data` is never `undefined` (unless a `select` changes
81`TData` to include `undefined`). `status` never resolves to `pending` in this overload's type, since
82`initialData` guarantees data upfront.
83β
84### Example
85β
86```vue
87<script setup lang="ts">
88import { useQuery } from '@tanstack/vue-query'
89β
90// `data` is `Post[]`, never `undefined`, thanks to `initialData` β even if a refetch fails,
91// so the list stays visible alongside the error.
92const { data, isError, error } = useQuery({
93 queryKey: ['posts'],
94 queryFn: fetchPosts,
95 initialData: [],
96})
97</script>
98β
99<template>
100 <span v-if="isError">Error: {{ error.message }}</span>
101 <ul>
102 <li v-for="post in data" :key="post.id">{{ post.title }}</li>
103 </ul>
104</template>
105```
106β
107<a id="call-signature-2"></a>
108β
109## Call Signature
110β
111```ts
112function useQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseQueryReturnType<TData, TError>;
113```
114β
115Defined in: [packages/vue-query/src/useQuery.ts:212](https://github.com/TanStack/query/blob/main/packages/vue-query/src/useQuery.ts#L212)
116β
117`enabled` tracks reactive dependencies automatically as a `ref`, a plain value, or a reactive getter
118(`() => ...`). `queryKey` reacts through a `ref` or a reactive getter for the array itself, or `ref`s and
119reactive getters as individual entries. Other options are read once when passed as a plain value, and stay
120reactive when passed as a `ref` or a `computed`.
121β
122### Type Parameters
123β
124#### TQueryFnData
125β
126`TQueryFnData` = `unknown`
127β
128#### TError
129β
130`TError` = `Error`
131β
132#### TData
133β
134`TData` = `TQueryFnData`
135β
136#### TQueryKey
137β
138`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
139β
140### Parameters
141β
142#### options
143β
144[`UndefinedInitialQueryOptions`](../type-aliases/UndefinedInitialQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
145β
146The [UndefinedInitialQueryOptions](../type-aliases/UndefinedInitialQueryOptions.md) to use β everything you can pass to `useQuery`.
147β
148#### queryClient?
149β
150[`QueryClient`](../classes/QueryClient.md)
151β
152Use this to use a custom `QueryClient`. Otherwise, the one provided by `VueQueryPlugin`
153will be used.
154β
155### Returns
156β
157[`UseQueryReturnType`](../type-aliases/UseQueryReturnType.md)\<`TData`, `TError`\>
158β
159The current query result. `status` is `pending` if there is no cached data to display, `error` if
160the last fetch attempt failed, or `success` if the query has data to display.
161β
162### Examples
163β
164A query key built from a reactive `ref` β the query refetches whenever `postId` changes:
165```vue
166<script setup lang="ts">
167import { ref } from 'vue'
168import { useQuery } from '@tanstack/vue-query'
169β
170const postId = ref(1)
171const { status, data, error } = useQuery({
172 queryKey: ['post', postId],
173 queryFn: () => fetchPost(postId.value),
174})
175</script>
176β
177<template>
178 <span v-if="status === 'pending'">Loading...</span>
179 <span v-else-if="status === 'error'">Error: {{ error.message }}</span>
180 <h1 v-else>{{ data.title }}</h1>
181</template>
182```
183β
184`select` derives whatever `data` a component needs from the cached value, without changing what's
185actually stored in the cache β the cache still holds the full `Post[]`, but `data` here is a `number`:
186```vue
187<script setup lang="ts">
188import { useQuery } from '@tanstack/vue-query'
189β
190const { data, isPending, isError, error } = useQuery({
191 queryKey: ['posts'],
192 queryFn: fetchPosts,
193 select: (posts) => posts.length,
194})
195</script>
196β
197<template>
198 <span v-if="isPending">Loading...</span>
199 <span v-else-if="isError">Error: {{ error.message }}</span>
200 <span v-else>{{ data }} posts</span>
201</template>
202```
203β
204A dependent query, only enabled once `postId` is set β use `isLoading`, not `isPending`, so the
205loading state doesn't show while the query is disabled:
206```vue
207<script setup lang="ts">
208import { ref } from 'vue'
209import { useQuery } from '@tanstack/vue-query'
210β
211const props = defineProps<{ postId: number | undefined }>()
212β
213const { data, isLoading, isError, error } = useQuery({
214 queryKey: ['post', props.postId],
215 queryFn: () => fetchPost(props.postId!),
216 enabled: () => props.postId != null,
217})
218</script>
219β
220<template>
221 <span v-if="props.postId == null">Select a post</span>
222 <span v-else-if="isLoading">Loading...</span>
223 <span v-else-if="isError">Error: {{ error.message }}</span>
224 <h1 v-else>{{ data?.title }}</h1>
225</template>
226```
227β
228Seeding a detail query from an already-cached list, to skip the loading state. `initialDataUpdatedAt` carries
229over the list's own fetch time, so that if you set a `staleTime`, it's measured from when the list was
230fetched rather than from now:
231```vue
232<script setup lang="ts">
233import { useQuery, useQueryClient } from '@tanstack/vue-query'
234β
235const props = defineProps<{ postId: number }>()
236const queryClient = useQueryClient()
237β
238const { data, isError, error } = useQuery({
239 queryKey: ['post', props.postId],
240 queryFn: () => fetchPost(props.postId),
241 initialData: () =>
242 queryClient
243 .getQueryData<Array<Post>>(['posts'])
244 ?.find((post) => post.id === props.postId),
245 initialDataUpdatedAt: () =>
246 queryClient.getQueryState(['posts'])?.dataUpdatedAt,
247})
248</script>
249β
250<template>
251 <span v-if="isError">Error: {{ error.message }}</span>
252 <h1 v-else>{{ data?.title }}</h1>
253</template>
254```
255β
256Paginated data, keeping the previous page's data visible while the next page loads:
257```vue
258<script setup lang="ts">
259import { ref } from 'vue'
260import { keepPreviousData, useQuery } from '@tanstack/vue-query'
261β
262const page = ref(0)
263β
264const { data, isPlaceholderData, isError, error } = useQuery({
265 queryKey: ['posts', page],
266 queryFn: () => fetchPosts(page.value),
267 placeholderData: keepPreviousData,
268})
269</script>
270β
271<template>
272 <span v-if="isError">Error: {{ error.message }}</span>
273 <template v-else>
274 <ul>
275 <li v-for="post in data" :key="post.id">{{ post.title }}</li>
276 </ul>
277 <button :disabled="isPlaceholderData" @click="page++">Next Page</button>
278 </template>
279</template>
280```
281β
282<a id="call-signature-3"></a>
283β
284## Call Signature
285β
286```ts
287function useQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: MaybeRefOrGetter<UseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>>, queryClient?: QueryClient): UseQueryReturnType<TData, TError>;
288```
289β
290Defined in: [packages/vue-query/src/useQuery.ts:285](https://github.com/TanStack/query/blob/main/packages/vue-query/src/useQuery.ts#L285)
291β
292Fallback overload for options whose `initialData` presence isn't statically known β for example, a
293`ref`/reactive object built up conditionally, rather than a plain object literal. Prefer one of the other
294overloads when possible, since they infer whether `data` can be `undefined` from `initialData` directly.
295β
296`enabled` tracks reactive dependencies automatically as a `ref`, a plain value, or a reactive getter
297(`() => ...`). `queryKey` reacts through a `ref` or a reactive getter for the array itself, or `ref`s and
298reactive getters as individual entries.
299β
300When `options` itself is a reactive getter, the whole object is re-evaluated on every change to its
301dependencies, so any option inside it β not just `queryKey` and `enabled` β can change over time.
302β
303### Type Parameters
304β
305#### TQueryFnData
306β
307`TQueryFnData` = `unknown`
308β
309#### TError
310β
311`TError` = `Error`
312β
313#### TData
314β
315`TData` = `TQueryFnData`
316β
317#### TQueryKey
318β
319`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
320β
321### Parameters
322β
323#### options
324β
325`MaybeRefOrGetter`\<[`UseQueryOptions`](../type-aliases/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryFnData`, `TQueryKey`\>\>
326β
327A `ref`, plain value, or reactive getter resolving to the [UseQueryOptions](../type-aliases/UseQueryOptions.md) to use.
328β
329#### queryClient?
330β
331[`QueryClient`](../classes/QueryClient.md)
332β
333Use this to use a custom `QueryClient`. Otherwise, the one provided by `VueQueryPlugin`
334will be used.
335β
336### Returns
337β
338[`UseQueryReturnType`](../type-aliases/UseQueryReturnType.md)\<`TData`, `TError`\>
339β
340The current query result, with `data` typed as possibly `undefined`.
341β
342### Examples
343β
344Passing a whole-options getter so `staleTime` reacts to a setting stored elsewhere, not just `queryKey`:
345```vue
346<script setup lang="ts">
347import { useQuery } from '@tanstack/vue-query'
348β
349const props = defineProps<{ id: number; staleTime: number }>()
350β
351const { data } = useQuery(() => ({
352 queryKey: ['post', props.id],
353 queryFn: () => fetchPost(props.id),
354 staleTime: props.staleTime,
355}))
356</script>
357β
358<template>
359 <h1 v-if="data">{{ data.title }}</h1>
360</template>
361```
362β
363`skipToken` disables the query in a type-safe way, without a non-null assertion on `props.postId` β
364`queryFn` is only ever called when it's defined. The whole-options getter re-evaluates `queryFn` on every
365change to `props.postId`. `queryFn` can also be a `computed`, but never a bare getter, since a function
366there is the query function itself. `refetch` doesn't work while `queryFn` is `skipToken` β use
367`enabled: false` instead if you need to trigger the query manually:
368```vue
369<script setup lang="ts">
370import { skipToken, useQuery } from '@tanstack/vue-query'
371β
372const props = defineProps<{ postId: number | undefined }>()
373β
374const { data, isLoading, isError, error } = useQuery(() => {
375 const postId = props.postId
376 return {
377 queryKey: ['post', postId],
378 queryFn: postId != null ? () => fetchPost(postId) : skipToken,
379 }
380})
381</script>
382β
383<template>
384 <span v-if="props.postId == null">Select a post</span>
385 <span v-else-if="isLoading">Loading...</span>
386 <span v-else-if="isError">Error: {{ error.message }}</span>
387 <h1 v-else>{{ data?.title }}</h1>
388</template>
389```
390β
391<a id="parameters-summary"></a>
392β
393## Parameters
394β
395### options
396β
397`MaybeRefOrGetter`\<[`UseQueryOptions`](../type-aliases/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryFnData`, `TQueryKey`\>\>
398β
399A `ref`, plain value, or reactive getter resolving to the [UseQueryOptions](../type-aliases/UseQueryOptions.md) to use.
400β
401### queryClient?
402β
403[`QueryClient`](../classes/QueryClient.md)
404β
405Use this to use a custom `QueryClient`. Otherwise, the one provided by `VueQueryPlugin`
406will be used.
407β
408<a id="returns-summary"></a>
409β
410## Returns
411β
412[`UseQueryReturnType`](../type-aliases/UseQueryReturnType.md)\<`TData`, `TError`\>
413β
414The current query result, with `data` typed as possibly `undefined`.