Network data loading
Fetch JSON from an HTTP endpoint and return the parsed response.
TanStack · Pipe
queryFn
queryFn is the data-fetching function for a TanStack Query. It receives QueryFunctionContext and must return defined data or throw; a configured default can provide it when omitted.
How it works
queryFn is the function TanStack Query invokes to obtain data for a query. It receives QueryFunctionContext, including the query key and cancellation signal, and must resolve usable data or throw an error; it may be omitted when a default query function is configured.
Syntax
(context: QueryFunctionContext<TQueryKey, TPageParam>) => TQueryFnData | Promise<TQueryFnData>Parameters
| Name | Type | Description |
|---|---|---|
context | QueryFunctionContext<TQueryKey, TPageParam> | Context containing the query key, page parameter when applicable, and other query execution context. |
Returns
TQueryFnData or Promise<TQueryFnData>; successful results must be defined, while failures should throw.
Key points
- queryFn defines how TanStack Query obtains the query's data.
- Its single input is a QueryFunctionContext object.
- The function may return the data directly or return a promise of that data.
- Defaults configured on the QueryClient can provide the function when an option-level function is absent.
Common mistakes
- Returning undefined or swallowing request failures violates the query function contract; resolve data or throw.
- Ensure every successful execution returns a defined value.
- A query function is optional only when an applicable default has been configured.
Example: A query function using QueryFunctionContext
import { useQuery } from '@tanstack/react-query'
type Todo = { id: number; title: string }
async function fetchTodos({ signal }: { signal: AbortSignal }): Promise<Todo[]> {
const response = await fetch('/api/todos', { signal })
if (!response.ok) throw new Error('Request failed')
return response.json()
}
export function Todos() {
const query = useQuery({
queryKey: ['todos'],
queryFn: fetchTodos,
})
return <pre>{JSON.stringify(query.data ?? [], null, 2)}</pre>
}The query function receives a context object, uses its abort signal for the request, and resolves parsed data or throws when the response fails.
When to use it
Context-aware requests
Use query context values to select the resource or pass cancellation to a request.
Default query functions
Share a standard fetching implementation through QueryClient defaults.
Interview questions
QWhat contract must a queryFn satisfy?
queryFn is the function used to request a query's data. It receives QueryFunctionContext and must return data asynchronously or throw an error; the resolved value must not be undefined.
Follow-up: What can make queryFn optional? A default query function configured with setQueryDefaults or setDefaultOptions can supply it when the query does not define one.
QWhat does queryFn receive?
The function receives QueryFunctionContext rather than only the query key. This context lets the implementation use query metadata such as the key and request cancellation signal.
Follow-up: How should a fetch-based query function handle cancellation? Pass the context's signal to the request so cancellation can propagate to the underlying fetch.
QWhen is queryFn optional?
A queryFn can be supplied directly in query options or inherited from query defaults. The option is required when no default query function is available.
Follow-up: Does the same rule apply across QueryClient fetching APIs? Query options are shared by observers and QueryClient methods, so the configured query function is used wherever those options apply.
Related
QueryFunctionContextQueryOptionsuseQueryQueryClientsetQueryDefaultssetDefaultOptions