Overview#
function useQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseQueryDefinedReturnType<TData, TError>;
function useQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseQueryReturnType<TData, TError>;
function 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>;
DefinedInitialQueryOptionsβUseQueryDefinedReturnType: This overload is selected wheninitialDatais known to be defined, so the resultingdatais typed as neverundefined(unless aselectchangesTDatato includeundefined). At runtime,datais stillundefinedifselectthrows on its first call.UndefinedInitialQueryOptionsβUseQueryReturnType:enabledaccepts aref, a plain boolean, or a zero-argument getter (() => ...): arefor a getter is tracked, while a plain boolean isn't tracked on its own. query-core's(query) => booleancallback is accepted too and is passed through untracked.queryKeyreacts through arefor a reactive getter for the array itself, orrefs and reactive getters as individual entries. Other options are read once when passed as a plain value, and stay reactive when passed as arefor acomputed.MaybeRefOrGetterβUseQueryReturnType: Fallback overload for options whoseinitialDatapresence isn't statically known β for example, aref/reactive object built up conditionally, rather than a plain object literal. Prefer one of the other overloads when possible, since they infer whetherdatacan beundefinedfrominitialDatadirectly.
See also: Parameters Β· Returns
Call Signature#
function useQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseQueryDefinedReturnType<TData, TError>;
Defined in: packages/vue-query/src/useQuery.ts:78
This overload is selected when initialData is known to be defined, so the resulting data is typed as never
undefined (unless a select changes TData to include undefined). At runtime, data is still undefined
if select throws on its first call.
enabled accepts a ref, a plain boolean, or a zero-argument getter (() => ...): a ref or a getter is
tracked, while a plain boolean isn't tracked on its own. query-core's (query) => boolean callback is
accepted too and is passed through untracked. queryKey reacts through a ref or a reactive getter for the
array itself, or refs 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.
Type Parameters#
TQueryFnData#
TQueryFnData = unknown
TError#
TError = Error
TData#
TData = TQueryFnData
TQueryKey#
TQueryKey extends readonly unknown[] = readonly unknown[]
Parameters#
options#
DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>
The DefinedInitialQueryOptions to use β everything you can pass to useQuery,
with initialData known to be defined.
queryClient?#
Use this to use a custom QueryClient. Otherwise, the one provided by VueQueryPlugin
will be used.
Returns#
UseQueryDefinedReturnType<TData, TError>
The current query result, typed so that status is success or error (status never resolves
to pending in this overload's type, since initialData guarantees data upfront). status is error if
the query has an error from a fetch that failed after its retries or if select threw, and success
otherwise. isSuccess/isError are derived boolean refs for convenience. state is that result as one
readonly reactive object β state.data, state.isPending, and the rest are plain values.
Example#
<script setup lang="ts">
import { useQuery } from '@tanstack/vue-query'
// `data` is `Post[]`, never `undefined`, thanks to `initialData` β even if a refetch fails,
// so the list stays visible alongside the error.
const { data, isError, error } = useQuery({
queryKey: ['posts'],
queryFn: fetchPosts,
initialData: [],
})
</script>
<template>
<span v-if="isError">Error: {{ error.message }}</span>
<ul>
<li v-for="post in data" :key="post.id">{{ post.title }}</li>
</ul>
</template>
Call Signature#
function useQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseQueryReturnType<TData, TError>;
Defined in: packages/vue-query/src/useQuery.ts:241
enabled accepts a ref, a plain boolean, or a zero-argument getter (() => ...): a ref or a getter is
tracked, while a plain boolean isn't tracked on its own. query-core's (query) => boolean callback is
accepted too and is passed through untracked. queryKey reacts through a ref or a reactive getter for the
array itself, or refs 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.
Type Parameters#
TQueryFnData#
TQueryFnData = unknown
TError#
TError = Error
TData#
TData = TQueryFnData
TQueryKey#
TQueryKey extends readonly unknown[] = readonly unknown[]
Parameters#
options#
UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>
The UndefinedInitialQueryOptions to use β everything you can pass to useQuery.
queryClient?#
Use this to use a custom QueryClient. Otherwise, the one provided by VueQueryPlugin
will be used.
Returns#
UseQueryReturnType<TData, TError>
The current query result. status is error if the query has an error from a fetch that failed
after its retries or if select threw, success if the query has cached data (even if select returns
undefined) or data from placeholderData, and pending otherwise. isPending/isSuccess/isError are
derived boolean refs for convenience. state is that result as one readonly reactive object β
state.data, state.isPending, and the rest are plain values, and state.status === 'success' narrows
state.data to TData.
Examples#
A query key built from a reactive ref β the query refetches whenever postId changes:
<script setup lang="ts">
import { ref } from 'vue'
import { useQuery } from '@tanstack/vue-query'
const postId = ref(1)
const { status, data, error } = useQuery({
queryKey: ['post', postId],
queryFn: () => fetchPost(postId.value),
})
</script>
<template>
<span v-if="status === 'pending'">Loading...</span>
<span v-else-if="status === 'error'">Error: {{ error.message }}</span>
<h1 v-else>{{ data.title }}</h1>
</template>
select derives whatever data a component needs from the cached value, without changing what's
actually stored in the cache β the cache still holds the full Post[], but data here is a number:
<script setup lang="ts">
import { useQuery } from '@tanstack/vue-query'
const { data, isPending, isError, error } = useQuery({
queryKey: ['posts'],
queryFn: fetchPosts,
select: (posts) => posts.length,
})
</script>
<template>
<span v-if="isPending">Loading...</span>
<span v-else-if="isError">Error: {{ error.message }}</span>
<span v-else>{{ data }} posts</span>
</template>
A dependent query, only enabled once postId is set β use isLoading, not isPending, so the
loading state doesn't show while the query is disabled:
<script setup lang="ts">
import { ref } from 'vue'
import { useQuery } from '@tanstack/vue-query'
const props = defineProps<{ postId: number | undefined }>()
const { data, isLoading, isError, error } = useQuery({
queryKey: ['post', props.postId],
queryFn: () => fetchPost(props.postId!),
enabled: () => props.postId != null,
})
</script>
<template>
<span v-if="props.postId == null">Select a post</span>
<span v-else-if="isLoading">Loading...</span>
<span v-else-if="isError">Error: {{ error.message }}</span>
<h1 v-else>{{ data?.title }}</h1>
</template>
Seeding a detail query from an already-cached list, to skip the loading state. initialDataUpdatedAt carries
over the list's own fetch time, so that if you set a staleTime, it's measured from when the list was
fetched rather than from now:
<script setup lang="ts">
import { useQuery, useQueryClient } from '@tanstack/vue-query'
const props = defineProps<{ postId: number }>()
const queryClient = useQueryClient()
const { data, isError, error } = useQuery({
queryKey: ['post', props.postId],
queryFn: () => fetchPost(props.postId),
initialData: () =>
queryClient
.getQueryData<Array<Post>>(['posts'])
?.find((post) => post.id === props.postId),
initialDataUpdatedAt: () =>
queryClient.getQueryState(['posts'])?.dataUpdatedAt,
})
</script>
<template>
<span v-if="isError">Error: {{ error.message }}</span>
<h1 v-else>{{ data?.title }}</h1>
</template>
Paginated data, keeping the previous page's data visible while the next page loads:
<script setup lang="ts">
import { ref } from 'vue'
import { keepPreviousData, useQuery } from '@tanstack/vue-query'
const page = ref(0)
const { data, isPlaceholderData, isError, error } = useQuery({
queryKey: ['posts', page],
queryFn: () => fetchPosts(page.value),
placeholderData: keepPreviousData,
})
</script>
<template>
<span v-if="isError">Error: {{ error.message }}</span>
<template v-else>
<ul>
<li v-for="post in data" :key="post.id">{{ post.title }}</li>
</ul>
<button :disabled="isPlaceholderData" @click="page++">Next Page</button>
</template>
</template>
state keeps data, error, status, and isPending on one reactive object, so a status check
narrows data and you never read .value:
<script setup lang="ts">
import { useQuery } from '@tanstack/vue-query'
const { state } = useQuery({
queryKey: ['post'],
queryFn: fetchPost,
})
</script>
<template>
<span v-if="state.status === 'pending'">Loading...</span>
<span v-else-if="state.status === 'error'">Error: {{ state.error.message }}</span>
<h1 v-else>{{ state.data.title }}</h1>
</template>
Call Signature#
function 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>;
Defined in: packages/vue-query/src/useQuery.ts:320
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.
enabled accepts a ref, a plain boolean, or a zero-argument getter (() => ...): a ref or a getter is
tracked, while a plain boolean isn't tracked on its own. query-core's (query) => boolean callback is
accepted too and is passed through untracked. queryKey reacts through a ref or a reactive getter for the
array itself, or refs and reactive getters as individual entries.
When options itself is a reactive getter, the whole object is re-evaluated on every change to its
dependencies, so any option inside it β not just queryKey and enabled β can change over time.
Type Parameters#
TQueryFnData#
TQueryFnData = unknown
TError#
TError = Error
TData#
TData = TQueryFnData
TQueryKey#
TQueryKey extends readonly unknown[] = readonly unknown[]
Parameters#
options#
MaybeRefOrGetter<UseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>>
A ref, plain value, or reactive getter resolving to the UseQueryOptions to use.
queryClient?#
Use this to use a custom QueryClient. Otherwise, the one provided by VueQueryPlugin
will be used.
Returns#
UseQueryReturnType<TData, TError>
The current query result. status is error if the query has an error from a fetch that failed
after its retries or if select threw, success if the query has cached data (even if select returns
undefined) or data from placeholderData, and pending otherwise. isPending/isSuccess/isError are
derived boolean refs for convenience. state is that result as one readonly reactive object β
state.data, state.isPending, and the rest are plain values, and state.status === 'success' narrows
state.data to TData.
Examples#
Passing a whole-options getter so staleTime reacts to a setting stored elsewhere, not just queryKey:
<script setup lang="ts">
import { useQuery } from '@tanstack/vue-query'
const props = defineProps<{ id: number; staleTime: number }>()
const { data } = useQuery(() => ({
queryKey: ['post', props.id],
queryFn: () => fetchPost(props.id),
staleTime: props.staleTime,
}))
</script>
<template>
<h1 v-if="data">{{ data.title }}</h1>
</template>
skipToken disables the query in a type-safe way, without a non-null assertion on props.postId β
queryFn is only ever called when it's defined. The whole-options getter re-evaluates queryFn on every
change to props.postId. queryFn can also be a computed, but never a bare getter, since a function
there is the query function itself. refetch doesn't work while queryFn is skipToken β use
enabled: false instead if you need to trigger the query manually:
<script setup lang="ts">
import { skipToken, useQuery } from '@tanstack/vue-query'
const props = defineProps<{ postId: number | undefined }>()
const { data, isLoading, isError, error } = useQuery(() => {
const postId = props.postId
return {
queryKey: ['post', postId],
queryFn: postId != null ? () => fetchPost(postId) : skipToken,
}
})
</script>
<template>
<span v-if="props.postId == null">Select a post</span>
<span v-else-if="isLoading">Loading...</span>
<span v-else-if="isError">Error: {{ error.message }}</span>
<h1 v-else>{{ data?.title }}</h1>
</template>
Parameters#
options#
MaybeRefOrGetter<UseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>>
A ref, plain value, or reactive getter resolving to the UseQueryOptions to use.
queryClient?#
Use this to use a custom QueryClient. Otherwise, the one provided by VueQueryPlugin
will be used.
Returns#
UseQueryReturnType<TData, TError>
The current query result. status is error if the query has an error from a fetch that failed
after its retries or if select threw, success if the query has cached data (even if select returns
undefined) or data from placeholderData, and pending otherwise. isPending/isSuccess/isError are
derived boolean refs for convenience. state is that result as one readonly reactive object β
state.data, state.isPending, and the rest are plain values, and state.status === 'success' narrows
state.data to TData.