QueryClient

The QueryClient is the core class that manages query and mutation state.

The QueryClient is the central class in TanStack Query that manages all query and mutation caches. It provides methods to fetch, cache, and synchronize server state.

Constructor

Creates a new QueryClient instance.

const queryClient = new QueryClient(config?: QueryClientConfig)

config · QueryClientConfig

Configuration options for the QueryClient

Show properties

queryCache · QueryCache

Custom QueryCache instance. If not provided, a new one will be created.

mutationCache · MutationCache

Custom MutationCache instance. If not provided, a new one will be created.

defaultOptions · DefaultOptions

Default options for queries and mutations.

Show properties

queries · QueryObserverOptions

Default options for all queries.

mutations · MutationObserverOptions

Default options for all mutations.

Example

import { QueryClient } from '@tanstack/query-core'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5 minutes
      gcTime: 1000 * 60 * 10, // 10 minutes
    },
  },
})

Methods

fetchQuery

Fetches a query and returns a promise with the data. If the query exists and the data is not stale, it will return the cached data.

fetchQuery<TQueryFnData, TError, TData, TQueryKey>(
  options: FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>
): Promise<TData>

options · FetchQueryOptions · required

Options for fetching the query

Show properties

queryKey · QueryKey · required

A unique key for the query.

queryFn · QueryFunction · required

The function that the query will use to request data.

staleTime · number | ((query: Query) => number)

Time in milliseconds after which data is considered stale.

Promise<TData> · Promise

Returns a promise that resolves with the query data.

Example

const data = await queryClient.fetchQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
})

prefetchQuery

Prefetches a query and caches the result. Unlike fetchQuery, it does not return the data and does not throw errors.

prefetchQuery<TQueryFnData, TError, TData, TQueryKey>(
  options: FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>
): Promise<void>

options · FetchQueryOptions · required

Same options as fetchQuery.

Promise<void> · Promise

Returns a promise that resolves when the query is prefetched.

Example

await queryClient.prefetchQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
})

fetchInfiniteQuery

Fetches an infinite query and returns a promise with the infinite data structure.

fetchInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(
  options: FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
): Promise<InfiniteData<TData, TPageParam>>

options · FetchInfiniteQueryOptions · required

Options for fetching the infinite query

Show properties

queryKey · QueryKey · required

A unique key for the query.

queryFn · QueryFunction · required

The function that fetches pages.

initialPageParam · TPageParam · required

The default page param to use when fetching the first page.

getNextPageParam · (lastPage, allPages, lastPageParam, allPageParams) => TPageParam | undefined · required

Function to get the next page param.

getPreviousPageParam · (firstPage, allPages, firstPageParam, allPageParams) => TPageParam | undefined

Function to get the previous page param.

pages · number

The number of pages to fetch.

Promise<InfiniteData> · Promise

Returns a promise that resolves with the infinite query data.

prefetchInfiniteQuery

Prefetches an infinite query and caches the result.

prefetchInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(
  options: FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
): Promise<void>

getQueryData

Returns the cached data for a query. This is a synchronous, non-reactive way to read data.

getQueryData<TQueryFnData, TTaggedQueryKey>(
  queryKey: TTaggedQueryKey
): TQueryFnData | undefined

queryKey · QueryKey · required

The query key to get data for.

TQueryFnData | undefined · Data

Returns the cached data or undefined if not found.

Example

const data = queryClient.getQueryData(['todos'])

Do not use this inside components, as it won’t receive updates. Use useQuery instead.

setQueryData

Updates the cached data for a query. Can accept a value or an updater function.

setQueryData<TQueryFnData, TTaggedQueryKey>(
  queryKey: TTaggedQueryKey,
  updater: Updater<TQueryFnData | undefined, TQueryFnData | undefined>,
  options?: SetDataOptions
): TQueryFnData | undefined

queryKey · QueryKey · required

The query key to update data for.

updater · TQueryFnData | ((oldData: TQueryFnData | undefined) => TQueryFnData) · required

New data value or updater function.

options · SetDataOptions

Additional options for setting data.

TQueryFnData | undefined · Data

Returns the updated data.

Example

// Set with value
queryClient.setQueryData(['todos'], newTodos)

// Set with updater function
queryClient.setQueryData(['todos'], (old) => [...old, newTodo])

getQueriesData

Returns the cached data for multiple queries matching the provided filters.

getQueriesData<TQueryFnData, TQueryFilters>(
  filters: TQueryFilters
): Array<[QueryKey, TQueryFnData | undefined]>

filters · QueryFilters · required

Filters to match queries.

Array<[QueryKey, TQueryFnData | undefined]> · Array

Returns an array of [queryKey, data] tuples.

setQueriesData

Updates the cached data for multiple queries matching the provided filters.

setQueriesData<TQueryFnData, TQueryFilters>(
  filters: TQueryFilters,
  updater: Updater<TQueryFnData | undefined, TQueryFnData | undefined>,
  options?: SetDataOptions
): Array<[QueryKey, TQueryFnData | undefined]>

getQueryState

Returns the query state (data, status, timestamps, etc.) for a query.

getQueryState<TQueryFnData, TError, TTaggedQueryKey>(
  queryKey: TTaggedQueryKey
): QueryState<TQueryFnData, TError> | undefined

queryKey · QueryKey · required

The query key to get state for.

QueryState | undefined · QueryState

Returns the query state or undefined if not found.

Show properties

data · TQueryFnData | undefined

The cached data.

error · TError | null

The error if the query is in an error state.

status · 'pending' | 'error' | 'success'

The status of the query.

fetchStatus · 'fetching' | 'paused' | 'idle'

The fetch status of the query.

ensureQueryData

Ensures that query data is available. If data is not cached, it will fetch it.

ensureQueryData<TQueryFnData, TError, TData, TQueryKey>(
  options: EnsureQueryDataOptions<TQueryFnData, TError, TData, TQueryKey>
): Promise<TData>

options · EnsureQueryDataOptions · required

Options including queryKey, queryFn, and optional revalidateIfStale.

Promise<TData> · Promise

Returns a promise that resolves with the query data (either cached or freshly fetched).

ensureInfiniteQueryData

Ensures that infinite query data is available.

ensureInfiniteQueryData<TQueryFnData, TError, TData, TQueryKey, TPageParam>(
  options: EnsureInfiniteQueryDataOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
): Promise<InfiniteData<TData, TPageParam>>

invalidateQueries

Marks queries as stale and optionally refetches them.

invalidateQueries<TTaggedQueryKey>(
  filters?: InvalidateQueryFilters<TTaggedQueryKey>,
  options?: InvalidateOptions
): Promise<void>

filters · InvalidateQueryFilters

Filters to match queries to invalidate.

Show properties

queryKey · QueryKey

Query key to match.

exact · boolean

Whether to match the query key exactly.

refetchType · 'active' | 'inactive' | 'all' | 'none'

Which queries to refetch. Default is ‘active’.

options · InvalidateOptions

Additional options for invalidation.

Promise<void> · Promise

Returns a promise that resolves when invalidation is complete.

Example

// Invalidate all queries
await queryClient.invalidateQueries()

// Invalidate specific queries
await queryClient.invalidateQueries({ queryKey: ['todos'] })

// Invalidate without refetching
await queryClient.invalidateQueries(
  { queryKey: ['todos'] },
  { refetchType: 'none' }
)

refetchQueries

Refetches queries matching the provided filters.

refetchQueries<TTaggedQueryKey>(
  filters?: RefetchQueryFilters<TTaggedQueryKey>,
  options?: RefetchOptions
): Promise<void>

filters · RefetchQueryFilters

Filters to match queries to refetch.

Show properties

queryKey · QueryKey

Query key to match.

type · 'active' | 'inactive' | 'all'

Which queries to refetch. Default is ‘active’.

exact · boolean

Whether to match the query key exactly.

stale · boolean

Only refetch stale queries.

options · RefetchOptions

Additional options for refetching.

Show properties

cancelRefetch · boolean

Whether to cancel any ongoing refetch. Default is true.

throwOnError · boolean

Whether to throw errors.

Promise<void> · Promise

Returns a promise that resolves when refetching is complete.

Example

// Refetch all active queries
await queryClient.refetchQueries()

// Refetch specific queries
await queryClient.refetchQueries({ queryKey: ['todos'] })

// Refetch all queries (including inactive)
await queryClient.refetchQueries({ type: 'all' })

cancelQueries

Cancels ongoing queries matching the provided filters.

cancelQueries<TTaggedQueryKey>(
  filters?: QueryFilters<TTaggedQueryKey>,
  cancelOptions?: CancelOptions
): Promise<void>

filters · QueryFilters

Filters to match queries to cancel.

cancelOptions · CancelOptions

Options for cancellation.

Show properties

revert · boolean

Whether to revert to previous data. Default is true.

Promise<void> · Promise

Returns a promise that resolves when cancellation is complete.

Example

await queryClient.cancelQueries({ queryKey: ['todos'] })

resetQueries

Resets queries to their initial state and optionally refetches them.

resetQueries<TTaggedQueryKey>(
  filters?: QueryFilters<TTaggedQueryKey>,
  options?: ResetOptions
): Promise<void>

filters · QueryFilters

Filters to match queries to reset.

options · ResetOptions

Options for resetting.

Promise<void> · Promise

Returns a promise that resolves when reset is complete.

removeQueries

Removes queries from the cache matching the provided filters.

removeQueries<TTaggedQueryKey>(
  filters?: QueryFilters<TTaggedQueryKey>
): void

filters · QueryFilters

Filters to match queries to remove.

Example

queryClient.removeQueries({ queryKey: ['todos'], type: 'inactive' })

isFetching

Returns the number of queries currently fetching.

isFetching<TQueryFilters>(
  filters?: TQueryFilters
): number

filters · QueryFilters

Filters to match queries.

number · number

The number of queries currently fetching.

Example

const isFetching = queryClient.isFetching()
const isFetchingTodos = queryClient.isFetching({ queryKey: ['todos'] })

isMutating

Returns the number of mutations currently executing.

isMutating<TMutationFilters>(
  filters?: TMutationFilters
): number

filters · MutationFilters

Filters to match mutations.

number · number

The number of mutations currently executing.

getQueryCache

Returns the QueryCache instance used by this client.

getQueryCache(): QueryCache

QueryCache · QueryCache

The QueryCache instance.

getMutationCache

Returns the MutationCache instance used by this client.

getMutationCache(): MutationCache

MutationCache · MutationCache

The MutationCache instance.

getDefaultOptions

Returns the default options for this client.

getDefaultOptions(): DefaultOptions

DefaultOptions · DefaultOptions

The default options.

setDefaultOptions

Sets the default options for this client.

setDefaultOptions(options: DefaultOptions): void

options · DefaultOptions · required

The new default options.

setQueryDefaults

Sets default options for queries matching a specific query key.

setQueryDefaults<TQueryFnData, TError, TData, TQueryData>(
  queryKey: QueryKey,
  options: Partial<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData>>
): void

queryKey · QueryKey · required

The query key to set defaults for.

options · Partial<QueryObserverOptions> · required

The default options for this query key.

Example

queryClient.setQueryDefaults(['todos'], {
  staleTime: 1000 * 60 * 5,
})

getQueryDefaults

Gets the default options for queries matching a specific query key.

getQueryDefaults(queryKey: QueryKey): Partial<QueryObserverOptions>

queryKey · QueryKey · required

The query key to get defaults for.

Partial<QueryObserverOptions> · object

The default options for this query key.

setMutationDefaults

Sets default options for mutations matching a specific mutation key.

setMutationDefaults<TData, TError, TVariables, TOnMutateResult>(
  mutationKey: MutationKey,
  options: Partial<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>>
): void

mutationKey · MutationKey · required

The mutation key to set defaults for.

options · Partial<MutationObserverOptions> · required

The default options for this mutation key.

getMutationDefaults

Gets the default options for mutations matching a specific mutation key.

getMutationDefaults(mutationKey: MutationKey): Partial<MutationObserverOptions>

mount

Mounts the QueryClient, setting up focus and online event listeners.

mount(): void

unmount

Unmounts the QueryClient, removing focus and online event listeners.

unmount(): void

clear

Clears all caches (queries and mutations).

clear(): void

Example

queryClient.clear()

resumePausedMutations

Resumes all paused mutations.

resumePausedMutations(): Promise<unknown>

Promise<unknown> · Promise

Returns a promise that resolves when all paused mutations have resumed.