--- id: queryOptions title: queryOptions redirect_from: - framework/react/reference/queryOptions --- ## Overview ```ts function queryOptions(options: DefinedInitialDataOptions): DefinedInitialDataOptions & QueryKeyWithDataTag; function queryOptions(options: UnusedSkipTokenOptions): UnusedSkipTokenOptions & QueryKeyWithDataTag; function queryOptions(options: UndefinedInitialDataOptions): UndefinedInitialDataOptions & QueryKeyWithDataTag; ``` - [`DefinedInitialDataOptions` → `DefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. - [`UnusedSkipTokenOptions` → `UnusedSkipTokenOptions & QueryKeyWithDataTag`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. - [`UndefinedInitialDataOptions` → `UndefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-3): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) ## Call Signature ```ts function queryOptions(options: DefinedInitialDataOptions): DefinedInitialDataOptions & QueryKeyWithDataTag; ``` Defined in: [packages/react-query/src/queryOptions.ts:141](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L141) You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. 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`). ### Type Parameters #### TQueryFnData `TQueryFnData` = `unknown` #### TError `TError` = `Error` #### TData `TData` = `TQueryFnData` #### TQueryKey `TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[] ### Parameters #### options [`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> The [DefinedInitialDataOptions](../type-aliases/DefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`, with `initialData` known to be defined. ### Returns [`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. ### See - [useQuery](useQuery.md) to run a query with these options. - [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern. ### Example ```tsx import { queryOptions, useQuery } from '@tanstack/react-query' export const postsOptions = queryOptions({ queryKey: ['posts'], queryFn: fetchPosts, initialData: [], }) function Posts() { // `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(postsOptions) return (
{isError ? Error: {error.message} : null}
    {data.map((post) =>
  • {post.title}
  • )}
) } ``` ## Call Signature ```ts function queryOptions(options: UnusedSkipTokenOptions): UnusedSkipTokenOptions & QueryKeyWithDataTag; ``` Defined in: [packages/react-query/src/queryOptions.ts:180](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L180) You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. ### Type Parameters #### TQueryFnData `TQueryFnData` = `unknown` #### TError `TError` = `Error` #### TData `TData` = `TQueryFnData` #### TQueryKey `TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[] ### Parameters #### options [`UnusedSkipTokenOptions`](../type-aliases/UnusedSkipTokenOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> The [UnusedSkipTokenOptions](../type-aliases/UnusedSkipTokenOptions.md) to use — everything you can pass to `useQuery`. ### Returns [`UnusedSkipTokenOptions`](../type-aliases/UnusedSkipTokenOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. ### See - [useQuery](useQuery.md) to run a query with these options. - [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern. ### Example A parameterized factory, so the same options object can be reused per `id`: ```tsx import { queryOptions, useQuery } from '@tanstack/react-query' export const postOptions = (id: string) => queryOptions({ queryKey: ['post', id], queryFn: () => fetchPost(id), }) function Post({ id }: { id: string }) { const { data, isPending, isError, error } = useQuery(postOptions(id)) if (isPending) return 'Loading...' if (isError) return Error: {error.message} return

{data.title}

} ``` ## Call Signature ```ts function queryOptions(options: UndefinedInitialDataOptions): UndefinedInitialDataOptions & QueryKeyWithDataTag; ``` Defined in: [packages/react-query/src/queryOptions.ts:241](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L241) You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. ### Type Parameters #### TQueryFnData `TQueryFnData` = `unknown` #### TError `TError` = `Error` #### TData `TData` = `TQueryFnData` #### TQueryKey `TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[] ### Parameters #### options [`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`. ### Returns [`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. ### Remarks This is the only overload that accepts `queryFn: skipToken`, shown below. ### See - [useQuery](useQuery.md) to run a query with these options. - [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern. ### Examples A parameterized factory, so the same options object can be reused per `id`: ```tsx import { queryOptions, useQuery } from '@tanstack/react-query' export const postOptions = (id: string) => queryOptions({ queryKey: ['post', id], queryFn: () => fetchPost(id), }) function Post({ id }: { id: string }) { const { data, isPending, isError, error } = useQuery(postOptions(id)) if (isPending) return 'Loading...' if (isError) return Error: {error.message} return

{data.title}

} ``` A factory that disables the query, type safe, until `postId` is set: ```tsx import { queryOptions, skipToken, useQuery } from '@tanstack/react-query' export const postOptions = (postId: number | undefined) => queryOptions({ queryKey: ['post', postId], queryFn: postId != null ? () => fetchPost(postId) : skipToken, }) function Post({ postId }: { postId: number | undefined }) { const { data, isLoading, isError, error } = useQuery(postOptions(postId)) if (postId == null) return 'Select a post' if (isLoading) return 'Loading...' if (isError) return Error: {error.message} return

{data?.title}

} ``` ## Parameters ### options [`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`. #### `options` properties Built from [`UseQueryOptions`](../interfaces/UseQueryOptions.md#properties). See the type above for what it changes. ## Returns [`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. ### Result properties Built from [`UseQueryOptions`](../interfaces/UseQueryOptions.md#properties), [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md#properties). See the type above for what it changes.