const queryResult = useQuery(queryKey, queryFn?, {cacheTime,enabled,initialData,initialDataUpdatedAt,isDataEqual,keepPreviousData,notifyOnChangeProps,notifyOnChangePropsExclusions,onError,onSettled,onSuccess,queryFnParamsFilter,queryKeyHashFn,refetchInterval,refetchIntervalInBackground,refetchOnMount,refetchOnReconnect,refetchOnWindowFocus,retry,retryDelay,staleTime,structuralSharing,useErrorBoundary,})const {data,dataUpdatedAt,error,errorUpdatedAt,failureCount,isError,isFetchedAfterMount,isFetching,isIdle,isLoading,isLoadingError,isPlaceholderData,isPreviousData,isRefetchError,isStale,isSuccess,refetch,remove,status,} = $queryResult// or using the object syntaxconst result = useQuery({queryKey,queryFn,enabled,})
Options
queryKey: string | unknown[]
enabled
is not set to false
).queryFn: (context: QueryFunctionContext) => Promise<TData>
QueryFunctionContext
object with the following variables:queryKey: QueryKey
enabled: boolean
false
to disable this query from automatically running.retry: boolean | number | (failureCount: number, error: TError) => boolean
false
, failed queries will not retry by default.true
, failed queries will retry infinitely.number
, e.g. 3
, failed queries will retry until the failed query count meets that number.retryDelay: (retryAttempt: number) => number
retryAttempt
integer and returns the delay to apply before the next attempt in milliseconds.attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)
applies exponential backoff.attempt => attempt * 1000
applies linear backoff.staleTime: number | Infinity
Infinity
, the data will never be considered stalecacheTime: number | Infinity
Infinity
, will disable garbage collectionrefetchInterval: false | number
refetchIntervalInBackground: boolean
true
, queries that are set to continuously refetch with a refetchInterval
will continue to refetch while their tab/window is in the backgroundrefetchOnMount: boolean | "always"
true
true
, the query will refetch on mount if the data is stale.false
, the query will not refetch on mount."always"
, the query will always refetch on mount.refetchOnWindowFocus: boolean | "always"
true
true
, the query will refetch on window focus if the data is stale.false
, the query will not refetch on window focus."always"
, the query will always refetch on window focus.refetchOnReconnect: boolean | "always"
true
true
, the query will refetch on reconnect if the data is stale.false
, the query will not refetch on reconnect."always"
, the query will always refetch on reconnect.notifyOnChangeProps: string[]
['data', 'error']
for example, the component will only re-render when the data
or error
properties change.notifyOnChangePropsExclusions: string[]
['isStale']
for example, the component will not re-render when the isStale
property changes.onSuccess: (data: TData) => void
onError: (error: TError) => void
onSettled: (data?: TData, error?: TError) => void
select: (data: TData) => unknown
initialData: TData | () => TData
staleTime
has been set.initialData
is persisted to the cacheinitialDataUpdatedAt: number | (() => number | undefined)
initialData
itself was last updated.placeholderData: TData | () => TData
loading
data and no initialData has been provided.placeholderData
is not persisted to the cachekeepPreviousData: boolean
false
data
will be kept when fetching new data because the query key changed.structuralSharing: boolean
true
false
, structural sharing between query results will be disabled.Returns
status: String
idle
if the query is idle. This only happens if a query is initialized with enabled: false
and no initial data is available.loading
if the query is in a "hard" loading state. This means there is no cached data and the query is currently fetching, eg isFetching === true
error
if the query attempt resulted in an error. The corresponding error
property has the error received from the attempted fetchsuccess
if the query has received a response with no errors and is ready to display its data. The corresponding data
property on the query is the data received from the successful fetch or if the query's enabled
property is set to false
and has not been fetched yet data
is the first initialData
supplied to the query on initialization.isIdle: boolean
status
variable above, provided for convenience.isLoading: boolean
status
variable above, provided for convenience.isSuccess: boolean
status
variable above, provided for convenience.isError: boolean
status
variable above, provided for convenience.isLoadingError: boolean
true
if the query failed while fetching for the first time.isRefetchError: boolean
true
if the query failed while refetching.data: TData
undefined
.dataUpdatedAt: number
status
as "success"
.error: null | TError
null
errorUpdatedAt: number
status
as "error"
.isStale: boolean
true
if the data in the cache is invalidated or if the data is older than the given staleTime
.isPlaceholderData: boolean
true
if the data shown is the placeholder data.isPreviousData: boolean
true
when keepPreviousData
is set and data from the previous query is returned.isFetchedAfterMount: boolean
true
if the query has been fetched after the component mounted.isFetching: boolean
true
so long as enabled
is set to false
true
if the query is currently fetching, including background fetching.failureCount: number
0
when the query succeeds.refetch: (options: { throwOnError: boolean }) => Promise<UseQueryResult>
throwOnError: true
optionremove: () => void
The latest TanStack news, articles, and resources, sent to your inbox.