Chapter 62: useQuery

Core Idea

The full option/return surface behind everything covered in the Guides chapters — most options here are explained in depth elsewhere (Important Defaults, Network Mode, Render Optimizations); this chapter is the compact reference for looking up an exact name, type, or default.

Key Concepts

• Signature: useQuery(options, queryClient?) — second argument is an optional explicit QueryClient override (defaults to the nearest QueryClientProvider's).
• Required options: queryKey (array); queryFn (unless a default query function is registered).
• Options already covered in depth elsewhere: enabled, networkMode, retry/retryOnMount/retryDelay, staleTime, gcTime, refetchInterval/refetchIntervalInBackground, refetchOnMount/refetchOnWindowFocus/refetchOnReconnect, notifyOnChangeProps, select, initialData/initialDataUpdatedAt, placeholderData, structuralSharing, throwOnError, meta.
• queryKeyHashFn: override how a queryKey is hashed to a cache-lookup string — rarely needed, an escape hatch for exotic key shapes the default JSON-based hash can't handle correctly.
• subscribed (default true): set false to mount a useQuery instance that doesn't subscribe to the cache at all — it won't trigger queryFn itself and won't react to updates from elsewhere. A narrow tool for cases needing the hook's shape without its normal reactivity.

Reference Tables

Return field	Meaning
status	'pending' | 'error' | 'success'
isPending/isSuccess/isError	Derived booleans from status
isLoadingError	Failed on the first fetch
isRefetchError	Failed on a background refetch (had prior data)
data	Last successfully resolved data (undefined by default)
dataUpdatedAt / errorUpdatedAt	Timestamp of most recent success/error
isStale	Invalidated, or older than staleTime
isPlaceholderData	Currently showing placeholderData, not real data
isFetched / isFetchedAfterMount	Has ever fetched / has fetched since this mount
fetchStatus	'fetching' | 'paused' | 'idle'
isFetching / isPaused	Derived from fetchStatus
isRefetching	isFetching && !isPending — background fetch, not initial
isLoading	isFetching && isPending — the actual first-fetch spinner flag
isInitialLoading	Deprecated alias of isLoading
isEnabled	Whether this observer is currently enabled
failureCount / failureReason	Current retry attempt count / latest error during retries
errorUpdateCount	Total error count across the query's lifetime
refetch(options)	Manual refetch trigger; { throwOnError, cancelRefetch }

Key Takeaways

1. isLoading (not isPending) is the correct flag for "show a spinner because this is genuinely fetching for the first time" — isPending alone is also true for disabled/lazy queries doing nothing.
2. isRefetching vs. isFetching: use isRefetching specifically to distinguish a background update from the initial fetch.
3. refetch()'s errors are only logged by default — pass throwOnError: true explicitly if a manual refetch failure should propagate.

Connects To

• Queries: the conceptual walkthrough of status/fetchStatus this reference formalizes.
• Query Retries, Network Mode, Render Optimizations: full guides for the options only summarized here.