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

useQuery.md

414 lines14.1 KB

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`.