--- id: useQuery title: useQuery redirect_from: - framework/vue/reference/useQuery --- ## Overview ```ts function useQuery(options: DefinedInitialQueryOptions, queryClient?: QueryClient): UseQueryDefinedReturnType; function useQuery(options: UndefinedInitialQueryOptions, queryClient?: QueryClient): UseQueryReturnType; function useQuery(options: MaybeRefOrGetter>, queryClient?: QueryClient): UseQueryReturnType; ``` - [`DefinedInitialQueryOptions` → `UseQueryDefinedReturnType`](#call-signature-1): This overload is selected when `initialData` is known to be defined, so the resulting `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`). - [`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`. - [`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. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) ## Call Signature ```ts function useQuery(options: DefinedInitialQueryOptions, queryClient?: QueryClient): UseQueryDefinedReturnType; ``` Defined in: [packages/vue-query/src/useQuery.ts:74](https://github.com/TanStack/query/blob/main/packages/vue-query/src/useQuery.ts#L74) This overload is selected when `initialData` is known to be defined, so the resulting `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`). `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`. ### Type Parameters #### TQueryFnData `TQueryFnData` = `unknown` #### TError `TError` = `Error` #### TData `TData` = `TQueryFnData` #### TQueryKey `TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[] ### Parameters #### options [`DefinedInitialQueryOptions`](../type-aliases/DefinedInitialQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> The [DefinedInitialQueryOptions](../type-aliases/DefinedInitialQueryOptions.md) to use — everything you can pass to `useQuery`, with `initialData` known to be defined. #### queryClient? [`QueryClient`](../classes/QueryClient.md) Use this to use a custom `QueryClient`. Otherwise, the one provided by `VueQueryPlugin` will be used. ### Returns [`UseQueryDefinedReturnType`](../type-aliases/UseQueryDefinedReturnType.md)\<`TData`, `TError`\> The current query result, typed so that `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`). `status` never resolves to `pending` in this overload's type, since `initialData` guarantees data upfront. ### Example ```vue ``` ## Call Signature ```ts function useQuery(options: UndefinedInitialQueryOptions, queryClient?: QueryClient): UseQueryReturnType; ``` Defined in: [packages/vue-query/src/useQuery.ts:213](https://github.com/TanStack/query/blob/main/packages/vue-query/src/useQuery.ts#L213) `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`. ### Type Parameters #### TQueryFnData `TQueryFnData` = `unknown` #### TError `TError` = `Error` #### TData `TData` = `TQueryFnData` #### TQueryKey `TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[] ### Parameters #### options [`UndefinedInitialQueryOptions`](../type-aliases/UndefinedInitialQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> The [UndefinedInitialQueryOptions](../type-aliases/UndefinedInitialQueryOptions.md) to use — everything you can pass to `useQuery`. #### queryClient? [`QueryClient`](../classes/QueryClient.md) Use this to use a custom `QueryClient`. Otherwise, the one provided by `VueQueryPlugin` will be used. ### Returns [`UseQueryReturnType`](../type-aliases/UseQueryReturnType.md)\<`TData`, `TError`\> The current query result. `status` is `pending` if there is no cached data to display, `error` if the last fetch attempt failed, or `success` if the query has data to display. ### Examples A query key built from a reactive `ref` — the query refetches whenever `postId` changes: ```vue ``` `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`: ```vue ``` 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: ```vue ``` 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: ```vue ``` Paginated data, keeping the previous page's data visible while the next page loads: ```vue ``` ## Call Signature ```ts function useQuery(options: MaybeRefOrGetter>, queryClient?: QueryClient): UseQueryReturnType; ``` Defined in: [packages/vue-query/src/useQuery.ts:286](https://github.com/TanStack/query/blob/main/packages/vue-query/src/useQuery.ts#L286) 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` 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. 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`](../type-aliases/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryFnData`, `TQueryKey`\>\> A `ref`, plain value, or reactive getter resolving to the [UseQueryOptions](../type-aliases/UseQueryOptions.md) to use. #### queryClient? [`QueryClient`](../classes/QueryClient.md) Use this to use a custom `QueryClient`. Otherwise, the one provided by `VueQueryPlugin` will be used. ### Returns [`UseQueryReturnType`](../type-aliases/UseQueryReturnType.md)\<`TData`, `TError`\> The current query result, with `data` typed as possibly `undefined`. ### Examples Passing a whole-options getter so `staleTime` reacts to a setting stored elsewhere, not just `queryKey`: ```vue ``` `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: ```vue ``` ## Parameters ### options `MaybeRefOrGetter`\<[`UseQueryOptions`](../type-aliases/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryFnData`, `TQueryKey`\>\> A `ref`, plain value, or reactive getter resolving to the [UseQueryOptions](../type-aliases/UseQueryOptions.md) to use. ### queryClient? [`QueryClient`](../classes/QueryClient.md) Use this to use a custom `QueryClient`. Otherwise, the one provided by `VueQueryPlugin` will be used. ## Returns [`UseQueryReturnType`](../type-aliases/UseQueryReturnType.md)\<`TData`, `TError`\> The current query result, with `data` typed as possibly `undefined`.