queryOptions

queryOptions packages a query key and its behavior into a reusable, type-aware options object. Its returned value brands the key with the query function's data and error types, allowing the same configuration to work with hooks and imperative QueryClient methods while preserving inference.

function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;

The supplied query options augmented with a QueryKeyWithDataTag carrying the query function's data and error types.

import { queryOptions, useQuery } from '@tanstack/react-query'

type Todo = { id: number; title: string }

async function fetchTodos(): Promise<Todo[]> {
  const response = await fetch('/api/todos')
  if (!response.ok) throw new Error('Request failed')
  return response.json()
}

const todosOptions = queryOptions({
  queryKey: ['todos'],
  queryFn: fetchTodos,
})

export function Todos() {
  const { data = [] } = useQuery(todosOptions)
  return <ul>{data.map(todo => <li key={todo.id}>{todo.title}</li>)}</ul>
}

Define one typed options object and reuse it with a query hook or imperative QueryClient API.