QueryClient

Defined in: packages/query-core/src/queryClient.ts:78

QueryClient is used to interact with a cache of queries and mutations. It owns a QueryCache and a MutationCache (creating default ones if none are passed in) and holds the default options that are applied to queries and mutations created through it.

Example

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: Infinity,
    },
  },
})

await queryClient.query({ queryKey: ['posts'], queryFn: fetchPosts })

Constructors

Constructor

new QueryClient(config?: QueryClientConfig): QueryClient;

Defined in: packages/query-core/src/queryClient.ts:88

Parameters

config?

QueryClientConfig = {}

Returns

QueryClient

Methods

cancelQueries()

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

Defined in: packages/query-core/src/queryClient.ts:461

Cancels outgoing fetches for queries matching the given filters. Most useful when performing optimistic updates, since any outgoing refetch that resolves afterwards would otherwise overwrite the optimistic update. By default (revert: true), a cancelled query's data is reverted to its state before the outgoing fetch started.

The returned promise never rejects, even if individual cancellations fail.

Type Parameters

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

filters?

QueryFilters<TTaggedQueryKey>

The filters that select which queries to cancel. Without filters, every query is cancelled.

cancelOptions?

CancelOptions = {}

Passed to each matched query's cancellation. revert defaults to true.

Returns

Promise<void>

A promise that resolves once every cancellation has settled.

Example

await queryClient.cancelQueries({ queryKey: ['posts'], exact: true })

clear()

clear(): void;

Defined in: packages/query-core/src/queryClient.ts:1168

Clears both the query cache and the mutation cache this client is connected to.

Returns

void

Example

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

const queryClient = new QueryClient()
queryClient.clear()

defaultMutationOptions()

defaultMutationOptions<T>(options?: T): T;

Defined in: packages/query-core/src/queryClient.ts:1143

The mutation counterpart of QueryClient#defaultQueryOptions. Called by framework adapters (e.g. inside useMutation) to merge the client's defaultOptions.mutations, then queryClient.setMutationDefaults for the given mutationKey, then the caller's options on top. A no-op if the options are already defaulted (_defaulted: true).

Type Parameters

T

T extends MutationOptions<any, any, any, any>

Parameters

options?

T

The mutation options passed by the caller.

Returns

T

The defaulted options.

defaultQueryOptions()

defaultQueryOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>(options: 
  | QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>
| DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>;

Defined in: packages/query-core/src/queryClient.ts:1054

Called by framework adapters (e.g. inside useQuery) to resolve the options passed by the caller into their final, defaulted form: merging the client's own defaultOptions.queries, then queryClient.setQueryDefaults for the given queryKey, then the caller's options on top. A no-op if the options are already defaulted (_defaulted: true).

Type Parameters

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryData

TQueryData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = never

Parameters

options

| QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam> | DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>

The query options passed by the caller.

Returns

DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>

The defaulted options, with queryHash and dependent defaults (e.g. refetchOnReconnect) filled in.

ensureInfiniteQueryData()

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

Defined in: packages/query-core/src/queryClient.ts:809

Returns the cached data of an infinite query, or fetches it if there is none. With revalidateIfStale, stale cached data is also refetched in the background.

Type Parameters

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = unknown

Parameters

options

EnsureInfiniteQueryDataOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

The infinite query options. If the query has no cached data yet, it is fetched with these options.

Returns

Promise<InfiniteData<TData, TPageParam>>

A promise that resolves to the cached InfiniteData, or to the fetched data if nothing was cached yet.

Deprecated

Use queryClient.infiniteQuery({ ...options, staleTime: 'static' }) instead. This method will be removed in the next major version.

ensureQueryData()

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

Defined in: packages/query-core/src/queryClient.ts:207

Returns the cached data of a query, or fetches it if there is none. With revalidateIfStale, stale cached data is also refetched in the background.

Type Parameters

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

options

EnsureQueryDataOptions<TQueryFnData, TError, TData, TQueryKey>

The query options. If the query has no cached data yet, it is fetched with these options.

Returns

Promise<TData>

A promise that resolves to the cached data, or to the fetched data if nothing was cached yet.

Deprecated

Use queryClient.query({ ...options, staleTime: 'static' }) instead. This method will be removed in the next major version.

fetchInfiniteQuery()

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

Defined in: packages/query-core/src/queryClient.ts:753

Fetches and caches an infinite query, or returns its cached data if it isn't stale.

Type Parameters

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = unknown

Parameters

options

FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

The infinite query options, including the queryKey, the queryFn, and the initialPageParam.

Returns

Promise<InfiniteData<TData, TPageParam>>

A promise that resolves to the cached or fetched InfiniteData, or rejects with the fetch error.

Deprecated

Use queryClient.infiniteQuery(options) instead. This method will be removed in the next major version.

fetchQuery()

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

Defined in: packages/query-core/src/queryClient.ts:647

Fetches and caches a query, or returns its cached data if it isn't stale. Unlike in observers, the fetch isn't retried unless retry is set.

Type Parameters

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = never

Parameters

options

FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

The query options, including the queryKey and the queryFn used if the query needs to fetch.

Returns

Promise<TData>

A promise that resolves to the cached or fetched data, or rejects with the fetch error.

Deprecated

Use queryClient.query(options) instead. This method will be removed in the next major version.

getDefaultOptions()

getDefaultOptions(): DefaultOptions;

Defined in: packages/query-core/src/queryClient.ts:893

Returns the default options that were set when creating the client, or via QueryClient#setDefaultOptions.

Returns

DefaultOptions

The client's current default options.

Example

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

const queryClient = new QueryClient()
const defaultOptions = queryClient.getDefaultOptions()

getMutationCache()

getMutationCache(): MutationCache;

Defined in: packages/query-core/src/queryClient.ts:877

Returns the mutation cache this client is connected to.

Returns

MutationCache

The MutationCache instance.

Example

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

const queryClient = new QueryClient()
const mutationCache = queryClient.getMutationCache()
const mutations = mutationCache.findAll({ status: 'pending' })

getMutationDefaults()

getMutationDefaults(mutationKey: readonly unknown[]): OmitKeyof<MutationObserverOptions<any, any, any, any>, "mutationKey">;

Defined in: packages/query-core/src/queryClient.ts:1026

Returns the default options registered for mutations whose mutation key partially matches the given mutationKey, via QueryClient#setMutationDefaults. If multiple registered defaults match, they are merged together in registration order.

Parameters

mutationKey

readonly unknown[]

The mutation key to look up registered defaults for.

Returns

OmitKeyof<MutationObserverOptions<any, any, any, any>, "mutationKey">

The merged default options of every registration that matches, or an empty object if none match.

Example

const defaultOptions = queryClient.getMutationDefaults(['addPost'])

getQueriesData()

getQueriesData<TQueryFnData, TQueryFilters>(filters: TQueryFilters): [readonly unknown[], TQueryFnData | undefined][];

Defined in: packages/query-core/src/queryClient.ts:253

Imperative (non-reactive) way to retrieve the cached data of multiple queries at once. Only queries matching the given filters are returned; if none match, an empty array is returned.

Because the matched queries can hold data of different shapes (e.g. a broad filter can match queries with unrelated data types), the TQueryFnData generic defaults to unknown rather than being inferred. Passing a more specific type is a convenience for call sites that know every matched query holds the same shape — it is not checked against the actual cache contents.

Type Parameters

TQueryFnData

TQueryFnData = unknown

TQueryFilters

TQueryFilters extends QueryFilters<any> = QueryFilters<readonly unknown[]>

Parameters

filters

TQueryFilters

The filters that select which queries to read.

Returns

[readonly unknown[], TQueryFnData | undefined][]

An array of query key and data pairs. The data is undefined for a query with no cached data.

See

QueryClient#getQueryData

Example

const data = queryClient.getQueriesData({ queryKey: ['posts'] })

getQueryCache()

getQueryCache(): QueryCache;

Defined in: packages/query-core/src/queryClient.ts:861

Returns the query cache this client is connected to.

Returns

QueryCache

The QueryCache instance.

Example

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

const queryClient = new QueryClient()
const queryCache = queryClient.getQueryCache()
const queries = queryCache.findAll({ queryKey: ['posts'] })

getQueryData()

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

Defined in: packages/query-core/src/queryClient.ts:187

Imperative (non-reactive) way to retrieve data for a QueryKey. Should only be used in callbacks or functions where reading the latest data is necessary, e.g. for optimistic updates.

Hint: Do not use this function inside a component, because it won't receive updates. Use useQuery to create a QueryObserver that subscribes to changes.

Type Parameters

TQueryFnData

TQueryFnData = unknown

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

TInferredQueryFnData

TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>

Parameters

queryKey

TTaggedQueryKey

The query key of the query to read.

Returns

TInferredQueryFnData | undefined

The cached data for the query, or undefined if no query with this key has been observed yet.

See

QueryClient#getQueriesData

getQueryDefaults()

getQueryDefaults(queryKey: readonly unknown[]): OmitKeyof<QueryObserverOptions<any, any, any, any, any>, "queryKey">;

Defined in: packages/query-core/src/queryClient.ts:966

Returns the default options registered for queries whose query key partially matches the given queryKey, via QueryClient#setQueryDefaults. If multiple registered defaults match, they are merged together in registration order.

Parameters

queryKey

readonly unknown[]

The query key to look up registered defaults for.

Returns

OmitKeyof<QueryObserverOptions<any, any, any, any, any>, "queryKey">

The merged default options of every registration that matches, or an empty object if none match.

Example

const defaultOptions = queryClient.getQueryDefaults(['posts'])

getQueryState()

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

Defined in: packages/query-core/src/queryClient.ts:370

Imperative (non-reactive) way to retrieve an existing query's state. If the query does not exist, undefined is returned.

Type Parameters

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

TInferredQueryFnData

TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>

TInferredError

TInferredError = InferErrorFromTag<TError, TTaggedQueryKey>

Parameters

queryKey

TTaggedQueryKey

The query key of the query to read.

Returns

| QueryState<TInferredQueryFnData, TInferredError> | undefined

The query's state, or undefined if no query with this key exists.

Example

const state = queryClient.getQueryState(['posts'])
console.log(state?.dataUpdatedAt)

infiniteQuery()

infiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options: InfiniteQueryExecuteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<TData[] extends InfiniteData<TQueryFnData, unknown>[] ? InfiniteData<TQueryFnData, TPageParam> : TData>;

Defined in: packages/query-core/src/queryClient.ts:722

Asynchronous method to fetch and cache an infinite query, resolving with an InfiniteData object or throwing with the error.

Behaves like QueryClient#query, accepting the same options (minus initialPageParam), plus the required initialPageParam, and an optional pages / getNextPageParam pair used to refetch a fixed number of pages from the start.

This method replaces the deprecated fetchInfiniteQuery, and — combined with { staleTime: 'static' } — the deprecated ensureInfiniteQueryData.

Type Parameters

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = InfiniteData<TQueryFnData, unknown>

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = unknown

Parameters

options

InfiniteQueryExecuteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

The infinite query options, including the queryKey, the queryFn, and the initialPageParam.

Returns

Promise<TData[] extends InfiniteData<TQueryFnData, unknown>[] ? InfiniteData<TQueryFnData, TPageParam> : TData>

A promise that resolves to the InfiniteData, or to the result of select if provided. It rejects with the error from the fetch or from select.

Example

try {
  const data = await queryClient.infiniteQuery({ queryKey, queryFn, initialPageParam: 0 })
  console.log(data.pages)
} catch (error) {
  console.log(error)
}

invalidateQueries()

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

Defined in: packages/query-core/src/queryClient.ts:494

Marks queries matching the given filters as invalidated. Unlike QueryClient#removeQueries, invalidated queries stay in the cache.

Unless filters.refetchType is 'none', matching queries are then refetched via QueryClient#refetchQueries, using filters.refetchType if set, otherwise filters.type, otherwise 'active'.

Type Parameters

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

filters?

InvalidateQueryFilters<TTaggedQueryKey>

The filters that select which queries to invalidate, plus refetchType to control which of them to refetch afterwards. Without filters, every query is invalidated.

options?

InvalidateOptions = {}

Passed to QueryClient#refetchQueries, e.g. cancelRefetch and throwOnError.

Returns

Promise<void>

A promise that resolves once the refetch settles, or immediately if refetchType is 'none'.

Example

await queryClient.invalidateQueries({ queryKey: ['posts'], refetchType: 'active' })

isFetching()

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

Defined in: packages/query-core/src/queryClient.ts:151

Returns the number of queries in the cache that are currently fetching, optionally matching a set of filters. This includes background-fetching, loading new pages, and loading more infinite query results.

Type Parameters

TQueryFilters

TQueryFilters extends QueryFilters<any> = QueryFilters<readonly unknown[]>

Parameters

filters?

TQueryFilters

Narrows down which fetching queries are counted. Without filters, every fetching query is counted.

Returns

number

The number of matching queries whose fetchStatus is 'fetching'.

Example

if (queryClient.isFetching()) {
  console.log('At least one query is fetching!')
}

isMutating()

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

Defined in: packages/query-core/src/queryClient.ts:171

Returns the number of mutations in the cache that are currently pending, optionally matching a set of filters.

Type Parameters

TMutationFilters

TMutationFilters extends MutationFilters<any, any, unknown, unknown> = MutationFilters<unknown, Error, unknown, unknown>

Parameters

filters?

TMutationFilters

Narrows down which pending mutations are counted. Without filters, every pending mutation is counted.

Returns

number

The number of matching mutations whose status is 'pending'.

Example

if (queryClient.isMutating()) {
  console.log('At least one mutation is pending!')
}

mount()

mount(): void;

Defined in: packages/query-core/src/queryClient.ts:103

Called by a framework adapter's QueryClientProvider-equivalent when it mounts, to start listening for focus/online events and resume paused mutations. Ref-counted via an internal mount count, so nested or multiple providers sharing the same QueryClient don't tear down the shared listeners until the last one unmounts.

Returns

void

prefetchInfiniteQuery()

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

Defined in: packages/query-core/src/queryClient.ts:781

Fetches and caches an infinite query like QueryClient#fetchInfiniteQuery, but ignores the result and any error.

Type Parameters

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = unknown

Parameters

options

FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

The infinite query options, including the queryKey, the queryFn, and the initialPageParam.

Returns

Promise<void>

A promise that resolves once the fetch settles. It never rejects.

Deprecated

Use queryClient.infiniteQuery(options) instead. You can swallow errors with .catch(noop). This method will be removed in the next major version.

prefetchQuery()

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

Defined in: packages/query-core/src/queryClient.ts:686

Fetches and caches a query like QueryClient#fetchQuery, but ignores the result and any error.

Type Parameters

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

options

FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>

The query options, including the queryKey and the queryFn used if the query needs to fetch.

Returns

Promise<void>

A promise that resolves once the fetch settles. It never rejects.

Deprecated

Use queryClient.query(options) instead. You can swallow errors with .catch(noop). This method will be removed in the next major version.

query()

query<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>(options: QueryExecuteOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>): Promise<TData>;

Defined in: packages/query-core/src/queryClient.ts:595

Asynchronous method to fetch and cache a query, resolving with the data or throwing with the error.

If the query already exists in the cache and its data is not stale (per the given staleTime), the cached data is returned without fetching. Otherwise, the query is fetched and the promise resolves once the fetch settles. If a select function is provided, it is applied to the data in both cases (cached or freshly fetched) before it is returned.

Unlike a reactive observer, retries are disabled by default here (retry: false) unless explicitly configured, since there is no component to catch a thrown error and retry through re-render.

The accepted options are QueryObserverOptions minus the fields that only make sense for a reactive observer — enabled, refetchInterval, refetchIntervalInBackground, refetchOnWindowFocus, refetchOnReconnect, refetchOnMount, retryOnMount, notifyOnChangeProps, throwOnError, suspense, and placeholderData are not part of this method's options.

This method replaces the deprecated fetchQuery, and — combined with { staleTime: 'static' } — the deprecated ensureQueryData.

Type Parameters

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = TQueryFnData

TQueryData

TQueryData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = never

Parameters

options

QueryExecuteOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>

The query options, including the queryKey and the queryFn used if the query needs to fetch.

Returns

Promise<TData>

A promise that resolves to the data, or to the result of select if provided. It rejects with the error from the fetch or from select.

Example

try {
  const data = await queryClient.query({ queryKey, queryFn, staleTime: 10000 })
} catch (error) {
  console.log(error)
}

refetchQueries()

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

Defined in: packages/query-core/src/queryClient.ts:535

Refetches queries matching the given filters, regardless of whether they are stale. Without filters, every query in the cache is refetched. Queries that are disabled, or static (only have observers with a static staleTime), are never refetched.

By default (cancelRefetch: true), a currently running fetch is cancelled before the new one starts. The returned promise resolves once all matching queries have settled; it does not reject on individual query failures unless throwOnError is set.

Type Parameters

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

filters?

RefetchQueryFilters<TTaggedQueryKey>

The filters that select which queries to refetch. Without filters, every query in the cache is included.

options?

RefetchOptions = {}

Set cancelRefetch to false to keep a running fetch instead of cancelling it, and throwOnError to true to reject when a refetch fails.

Returns

Promise<void>

A promise that resolves once every matched query has settled.

Example

// refetch all active queries partially matching a query key:
await queryClient.refetchQueries({ queryKey: ['posts'], type: 'active' })

removeQueries()

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

Defined in: packages/query-core/src/queryClient.ts:397

Removes queries from the cache that match the given filters. Unlike QueryClient#invalidateQueries or QueryClient#refetchQueries, this removes matching queries from the cache instead of refetching them. Without filters, every query in the cache is removed.

Type Parameters

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

filters?

QueryFilters<TTaggedQueryKey>

The filters that select which queries to remove. Without filters, every query is removed.

Returns

void

Example

queryClient.removeQueries({ queryKey: ['posts'], exact: true })

resetQueries()

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

Defined in: packages/query-core/src/queryClient.ts:422

Resets queries matching the given filters back to their initial state (e.g. any initialData), notifying subscribers rather than removing them. Active queries among the matched set are then refetched, and the returned promise resolves once that refetch settles.

Type Parameters

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

filters?

QueryFilters<TTaggedQueryKey>

The filters that select which queries to reset. Without filters, every query is reset.

options?

ResetOptions

Passed to the refetch of the active matched queries, e.g. cancelRefetch and throwOnError.

Returns

Promise<void>

A promise that resolves once the refetch of the active matched queries settles.

Example

await queryClient.resetQueries({ queryKey: ['posts'], exact: true })

resumePausedMutations()

resumePausedMutations(): Promise<unknown>;

Defined in: packages/query-core/src/queryClient.ts:842

Resumes mutations that were paused because there was no network connection. Does nothing (resolving immediately) if the client is currently offline.

Returns

Promise<unknown>

A promise that resolves once the resumed mutations have settled.

Example

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

const queryClient = new QueryClient()
await queryClient.resumePausedMutations()

setDefaultOptions()

setDefaultOptions(options: DefaultOptions): void;

Defined in: packages/query-core/src/queryClient.ts:914

Dynamically sets the default options for this client, overwriting any previously defined default options.

Parameters

options

DefaultOptions

The new default options for queries and mutations.

Returns

void

See

QueryClient#getDefaultOptions

Example

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

const queryClient = new QueryClient()
queryClient.setDefaultOptions({
  queries: {
    staleTime: Infinity,
  },
})

setMutationDefaults()

setMutationDefaults<TData, TError, TVariables, TOnMutateResult>(mutationKey: readonly unknown[], options: OmitKeyof<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): void;

Defined in: packages/query-core/src/queryClient.ts:996

Sets default options for mutations whose mutation key partially matches the given mutationKey. As with QueryClient#setQueryDefaults, the order of registration matters when several registered defaults match the same mutation key.

Type Parameters

TData

TData = unknown

TError

TError = Error

TVariables

TVariables = void

TOnMutateResult

TOnMutateResult = unknown

Parameters

mutationKey

readonly unknown[]

The mutation key that mutation keys are partially matched against.

options

OmitKeyof<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">

The default options applied to matching mutations.

Returns

void

See

QueryClient#getMutationDefaults

Example

queryClient.setMutationDefaults(['addPost'], { mutationFn: addPost })

setQueriesData()

setQueriesData<TQueryFnData, TQueryFilters>(
   filters: TQueryFilters, 
   updater: Updater<NoInfer<TQueryFnData> | undefined, NoInfer<TQueryFnData> | undefined>, 
   options?: SetDataOptions): [readonly unknown[], TQueryFnData | undefined][];

Defined in: packages/query-core/src/queryClient.ts:338

Synchronous way to immediately update the cached data of multiple queries at once, using filters or partial query key matching. Only queries that already exist and match the given filters are updated; no new cache entries are created. Internally this calls QueryClient#setQueryData for each matching query.

Type Parameters

TQueryFnData

TQueryFnData

TQueryFilters

TQueryFilters extends QueryFilters<any> = QueryFilters<readonly unknown[]>

Parameters

filters

TQueryFilters

The filters that select which existing queries to update.

updater

Updater<NoInfer<TQueryFnData> | undefined, NoInfer<TQueryFnData> | undefined>

Either the new data, or a function that receives each matched query's current data (which may be undefined) and returns the new data.

options?

SetDataOptions

Set updatedAt to override the timestamp the written data is recorded with.

Returns

[readonly unknown[], TQueryFnData | undefined][]

One [queryKey, data] tuple per matched query, in the same shape and with the same undefined case as QueryClient#setQueryData.

Example

queryClient.setQueriesData({ queryKey: ['posts'] }, (oldPosts) =>
  oldPosts ? oldPosts.filter((post) => post.id !== deletedId) : oldPosts,
)

setQueryData()

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

Defined in: packages/query-core/src/queryClient.ts:285

Synchronous way to immediately update a query's cached data. If the updater (or the value passed) resolves to undefined, the cache is left untouched and no query is created; otherwise, if the query does not exist yet, it will be created. To update multiple queries at once by partially matching query keys, use QueryClient#setQueriesData instead.

Updates must be performed immutably: do not mutate oldData, or data previously retrieved via QueryClient#getQueryData, in place.

Type Parameters

TQueryFnData

TQueryFnData = unknown

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

TInferredQueryFnData

TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>

Parameters

queryKey

TTaggedQueryKey

The query key to set data for.

updater

Updater<NoInfer<TInferredQueryFnData> | undefined, NoInfer<TInferredQueryFnData> | undefined>

Either the new data, or a function that receives the current data (which may be undefined) and returns the new data.

options?

SetDataOptions

Set updatedAt to override the timestamp the written data is recorded with.

Returns

NoInfer<TInferredQueryFnData> | undefined

The data that was written, or undefined if the updater returned undefined — in that case the write is skipped and the cache is left unchanged.

Example

queryClient.setQueryData(['posts'], newPosts)

// Or, using an updater function that receives the current data:
queryClient.setQueryData(['posts'], (oldPosts) => [...oldPosts, newPost])

setQueryDefaults()

setQueryDefaults<TQueryFnData, TError, TData, TQueryData>(queryKey: readonly unknown[], options: Partial<OmitKeyof<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData>, "queryKey">>): void;

Defined in: packages/query-core/src/queryClient.ts:934

Sets default options for queries whose query key partially matches the given queryKey.

If several registered query defaults match a given query key, they are merged together in registration order by QueryClient#getQueryDefaults, so register defaults from the most generic key to the least generic one — more specific defaults should be registered after more generic ones so they take precedence.

Type Parameters

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryData

TQueryData = TQueryFnData

Parameters

queryKey

readonly unknown[]

The query key that query keys are partially matched against.

options

Partial<OmitKeyof<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData>, "queryKey">>

The default options applied to matching queries.

Returns

void

Example

queryClient.setQueryDefaults(['posts'], { queryFn: fetchPosts })

await queryClient.query({ queryKey: ['posts'] })

unmount()

unmount(): void;

Defined in: packages/query-core/src/queryClient.ts:126

The inverse of QueryClient#mount — called by a framework adapter's QueryClientProvider-equivalent when it unmounts. Only tears down the focus/online listeners once the mount count returns to 0.

Returns

void