enabled option for dependent queries
The enabled option accepts a boolean or function (query: Query) => boolean and can be set to false to disable a query from automatically running. This is used for implementing dependent queries.
TanStack Query · React · all subjects
query configuration
20 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
retry option configuration
The retry option can be set as: false (failed queries will not retry), true (retry infinitely), a number like 3 (retry until failure count meets that number), or a function (failureCount: number, error: TError) => boolean. It defaults to 3 on the client and 0 on the server.
retryOnMount option
retryOnMount is a boolean or function (query: Query) => boolean that determines if the query will be retried on mount if it contains an error and has no data. It defaults to true. If set to a function, the function will be executed with the query to compute the value.
retryDelay option
retryDelay is a number or function (retryAttempt: number, error: TError) => number that specifies the delay in milliseconds before the next retry attempt. Example exponential backoff: attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000). Example linear backoff: attempt => attempt * 1000.
meta option
meta is an optional Record<string, unknown> that stores additional information on the query cache entry if set. It will be accessible wherever the query is available and is part of the QueryFunctionContext provided to the queryFn.
staleTime option
staleTime can be a number, 'static', or a function (query: Query) => number | 'static'. It defaults to 0. The time in milliseconds after which data is considered stale. If set to Infinity, data will not be considered stale unless manually invalidated. If set to 'static', data will never be considered stale.
queryKeyHashFn option
queryKeyHashFn is an optional function (queryKey: QueryKey) => string that is used to hash the queryKey to a string if specified.
refetchInterval option
refetchInterval can be a number, false, or a function (query: Query) => number | false | undefined. If set to a number, all queries will continuously refetch at this frequency in milliseconds. If set to a function, it will be executed with the query to compute a frequency.
refetchIntervalInBackground option
refetchIntervalInBackground is an optional boolean. If set to true, queries that are set to continuously refetch with a refetchInterval will continue to refetch while their tab/window is in the background.
refetchOnMount option
refetchOnMount can be a boolean, 'always', or a function (query: Query) => boolean | 'always'. It defaults to true. If true, the query will refetch on mount if data is stale. If false, no refetch on mount. If 'always', the query will always refetch on mount except when staleTime: 'static' is used. If a function, it will be executed with the query to compute the value.
refetchOnWindowFocus option
refetchOnWindowFocus can be a boolean, 'always', or a function (query: Query) => boolean | 'always'. It defaults to true. If true, the query will refetch on window focus if data is stale. If false, no refetch on window focus. If 'always', the query will always refetch on window focus except when staleTime: 'static' is used. If a function, it will be executed with the query to compute the value.
refetchOnReconnect option
refetchOnReconnect can be a boolean, 'always', or a function (query: Query) => boolean | 'always'. It defaults to true. If true, the query will refetch on reconnect if data is stale. If false, no refetch on reconnect. If 'always', the query will always refetch on reconnect except when staleTime: 'static' is used. If a function, it will be executed with the query to compute the value.
notifyOnChangeProps option
notifyOnChangeProps can be a string array, 'all', or a function () => string[] | 'all' | undefined. If set, the component will only re-render if any of the listed properties change. If set to 'all', the component opts out of smart tracking and re-renders whenever a query is updated. By default, access to properties is tracked and the component only re-renders when tracked properties change.
select option for data transformation
The select option is a function (data: TData) => unknown that transforms or selects a part of the data returned by the query function. It affects the returned data value but does not affect what gets stored in the query cache. The select function only runs if data changed or if the reference to the select function itself changes. Wrap in useCallback to optimize.
initialData option
initialData can be TData or () => TData. If set, this value will be used as the initial data for the query cache as long as the query hasn't been created or cached yet. If set to a function, it will be called once during shared/root query initialization and must synchronously return the initialData. Initial data is considered stale by default unless a staleTime has been set. initialData is persisted to the cache.
initialDataUpdatedAt option
initialDataUpdatedAt is an optional number or function () => number | undefined. If set, this value will be used as the time in milliseconds of when the initialData itself was last updated.
placeholderData option
placeholderData can be TData or a function (previousValue: TData | undefined, previousQuery: Query | undefined) => TData. If set, this value will be used as placeholder data for this query while the query is in the pending state. placeholderData is not persisted to the cache. The function receives previously watched query data if available as the first argument and the complete previousQuery instance as the second argument.
structuralSharing option
structuralSharing can be a boolean or function (oldData: unknown | undefined, newData: unknown) => unknown. It defaults to true. If false, structural sharing between query results is disabled. If a function, the old and new data values will be passed through it, which should combine them into resolved data. This allows retaining references from old data to improve performance even with non-serializable values.
subscribed option
subscribed is an optional boolean that defaults to true. If set to false, this instance of useQuery will not be subscribed to the cache, meaning it won't trigger the queryFn on its own and won't receive updates if data gets into cache by other means.
throwOnError option
throwOnError is undefined, boolean, or function (error: TError, query: Query) => boolean. It defaults to false. If true, errors will be thrown in the render phase and propagate to the nearest error boundary. If a function, it will be passed the error and query and should return a boolean indicating whether to show the error in an error boundary (true) or return the error as state (false).