useQuery
TheuseQuery hook is the primary way to fetch and cache data in TanStack Query. It subscribes to a query and returns the current state of the query.
Import
Signature
Type Parameters
The type of data returned by the query function
The type of error that can be thrown by the query function
The type of data returned by the select function (if provided), otherwise same as TQueryFnData
The type of the query key
Parameters
Configuration options for the query
A unique key for the query. Must be an array.
The function that will be called to fetch data. Receives a
QueryFunctionContext object.Set to
false to disable automatic query executionTime in milliseconds after data is considered stale. Set to
Infinity to disable automatic refetching.Time in milliseconds that unused/inactive cache data remains in memory. When a query’s cache becomes unused or inactive, that cache data will be garbage collected after this duration.
If set to a number, the query will continuously refetch at this frequency in milliseconds
If set to
true, the query will continue to refetch while the window is in the backgroundIf set to
true, the query will refetch on window focus if the data is staleIf set to
true, the query will refetch on mount if the data is staleIf set to
true, the query will refetch on reconnect if the data is staleNumber of retry attempts or function to determine if a request should be retried
Function that receives a retry attempt number and returns the delay to apply before the next attempt
Function to transform or select a part of the data returned by the query function
If set, this value will be used as the initial data for the query (as long as the query hasn’t been created or cached yet)
If set, this value will be used as the time (in milliseconds) of when the initialData itself was last updated
placeholderData
TQueryFnData | (previousData: TData | undefined, previousQuery: Query | undefined) => TQueryFnData
If set, this value will be used as the placeholder data for this particular query observer while the query is still in the pending state
Set this to
false to disable structural sharing between query resultsSet this to
true if you want errors to be thrown in the render phase and propagate to the nearest error boundaryControls when the query function is allowed to execute
If set, the component will only re-render when one of the listed properties change
Optional metadata that can be used by query client plugins
Set this to
false to unsubscribe this observer from updates to the query cacheOptional QueryClient instance to use. If not provided, the client from the nearest
QueryClientProvider will be used.Returns
The data returned by the query function (or
undefined if the query hasn’t successfully fetched yet)The error object for the query, if an error occurred
The status of the query:
pending: The query has no data yeterror: The query encountered an errorsuccess: The query was successful and data is available
The fetch status of the query:
fetching: The query is currently fetchingpaused: The query wanted to fetch, but it is pausedidle: The query is not fetching
Derived from
status. Will be true if the query is in pending statusDerived from
status. Will be true if the query is in success statusDerived from
status. Will be true if the query is in error statusDerived from
fetchStatus. Will be true whenever the query is fetching (including background refetching)Shorthand for
isPending && isFetching - useful for showing a loading spinner on initial loadWill be
true if the query failed while fetching for the first timeWill be
true if the query failed while refetchingWill be
true if the data in the cache is invalidated or if the data is older than the given staleTimeWill be
true if the data shown is placeholder dataFunction to manually refetch the query
Timestamp of when the data was last updated
Timestamp of when the error was last updated
The failure count for the query
The failure reason for the query retry