Migrating to TanStack Query v5

Breaking Changes#

v5 is a major version, so there are some breaking changes to be aware of:

Supports a single signature, one object#

useQuery and friends used to have many overloads in TypeScript: different ways how the function could be invoked. Not only was this tough to maintain, type wise, it also required a runtime check to see which types the first and the second parameter were, to correctly create options.

now we only support the object format.

useQuery(key, fn, options) 
useQuery({ queryKey, queryFn, ...options }) 
useInfiniteQuery(key, fn, options) 
useInfiniteQuery({ queryKey, queryFn, ...options }) 
useMutation(fn, options) 
useMutation({ mutationFn, ...options }) 
useIsFetching(key, filters) 
useIsFetching({ queryKey, ...filters }) 
useIsMutating(key, filters) 
useIsMutating({ mutationKey, ...filters }) 

useQuery(key, fn, options) 
useQuery({ queryKey, queryFn, ...options }) 
useInfiniteQuery(key, fn, options) 
useInfiniteQuery({ queryKey, queryFn, ...options }) 
useMutation(fn, options) 
useMutation({ mutationFn, ...options }) 
useIsFetching(key, filters) 
useIsFetching({ queryKey, ...filters }) 
useIsMutating(key, filters) 
useIsMutating({ mutationKey, ...filters }) 

queryClient.isFetching(key, filters) 
queryClient.isFetching({ queryKey, ...filters }) 
queryClient.ensureQueryData(key, filters) 
queryClient.ensureQueryData({ queryKey, ...filters }) 
queryClient.getQueriesData(key, filters) 
queryClient.getQueriesData({ queryKey, ...filters }) 
queryClient.setQueriesData(key, updater, filters, options) 
queryClient.setQueriesData({ queryKey, ...filters }, updater, options) 
queryClient.removeQueries(key, filters) 
queryClient.removeQueries({ queryKey, ...filters }) 
queryClient.resetQueries(key, filters, options) 
queryClient.resetQueries({ queryKey, ...filters }, options) 
queryClient.cancelQueries(key, filters, options) 
queryClient.cancelQueries({ queryKey, ...filters }, options) 
queryClient.invalidateQueries(key, filters, options) 
queryClient.invalidateQueries({ queryKey, ...filters }, options) 
queryClient.refetchQueries(key, filters, options) 
queryClient.refetchQueries({ queryKey, ...filters }, options) 
queryClient.fetchQuery(key, fn, options) 
queryClient.fetchQuery({ queryKey, queryFn, ...options }) 
queryClient.prefetchQuery(key, fn, options) 
queryClient.prefetchQuery({ queryKey, queryFn, ...options }) 
queryClient.fetchInfiniteQuery(key, fn, options) 
queryClient.fetchInfiniteQuery({ queryKey, queryFn, ...options }) 
queryClient.prefetchInfiniteQuery(key, fn, options) 
queryClient.prefetchInfiniteQuery({ queryKey, queryFn, ...options }) 

queryClient.isFetching(key, filters) 
queryClient.isFetching({ queryKey, ...filters }) 
queryClient.ensureQueryData(key, filters) 
queryClient.ensureQueryData({ queryKey, ...filters }) 
queryClient.getQueriesData(key, filters) 
queryClient.getQueriesData({ queryKey, ...filters }) 
queryClient.setQueriesData(key, updater, filters, options) 
queryClient.setQueriesData({ queryKey, ...filters }, updater, options) 
queryClient.removeQueries(key, filters) 
queryClient.removeQueries({ queryKey, ...filters }) 
queryClient.resetQueries(key, filters, options) 
queryClient.resetQueries({ queryKey, ...filters }, options) 
queryClient.cancelQueries(key, filters, options) 
queryClient.cancelQueries({ queryKey, ...filters }, options) 
queryClient.invalidateQueries(key, filters, options) 
queryClient.invalidateQueries({ queryKey, ...filters }, options) 
queryClient.refetchQueries(key, filters, options) 
queryClient.refetchQueries({ queryKey, ...filters }, options) 
queryClient.fetchQuery(key, fn, options) 
queryClient.fetchQuery({ queryKey, queryFn, ...options }) 
queryClient.prefetchQuery(key, fn, options) 
queryClient.prefetchQuery({ queryKey, queryFn, ...options }) 
queryClient.fetchInfiniteQuery(key, fn, options) 
queryClient.fetchInfiniteQuery({ queryKey, queryFn, ...options }) 
queryClient.prefetchInfiniteQuery(key, fn, options) 
queryClient.prefetchInfiniteQuery({ queryKey, queryFn, ...options }) 

queryCache.find(key, filters) 
queryCache.find({ queryKey, ...filters }) 
queryCache.findAll(key, filters) 
queryCache.findAll({ queryKey, ...filters }) 

queryCache.find(key, filters) 
queryCache.find({ queryKey, ...filters }) 
queryCache.findAll(key, filters) 
queryCache.findAll({ queryKey, ...filters }) 

now accepts queryKey only as an Argument#

argument is changed to accept only a

queryClient.getQueryData(queryKey, filters) 
queryClient.getQueryData(queryKey) 

queryClient.getQueryData(queryKey, filters) 
queryClient.getQueryData(queryKey) 

now accepts queryKey only as an Argument#

argument is changed to accept only a

queryClient.getQueryState(queryKey, filters) 
queryClient.getQueryState(queryKey) 

queryClient.getQueryState(queryKey, filters) 
queryClient.getQueryState(queryKey) 

Codemod#

To make the remove overloads migration easier, v5 comes with a codemod.

The codemod is a best efforts attempt to help you migrate the breaking change. Please review the generated code thoroughly! Also, there are edge cases that cannot be found by the code mod, so please keep an eye on the log output.

If you want to run it against or files, please use the command below:

npx jscodeshift@latest ./path/to/src/ \
  --extensions=js,jsx \
  --transform=./node_modules/@tanstack/react-query/build/codemods/src/v5/remove-overloads/remove-overloads.cjs

npx jscodeshift@latest ./path/to/src/ \
  --extensions=js,jsx \
  --transform=./node_modules/@tanstack/react-query/build/codemods/src/v5/remove-overloads/remove-overloads.cjs

If you want to run it against or files, please use the command below:

npx jscodeshift@latest ./path/to/src/ \
  --extensions=ts,tsx \
  --parser=tsx \
  --transform=./node_modules/@tanstack/react-query/build/codemods/src/v5/remove-overloads/remove-overloads.cjs

npx jscodeshift@latest ./path/to/src/ \
  --extensions=ts,tsx \
  --parser=tsx \
  --transform=./node_modules/@tanstack/react-query/build/codemods/src/v5/remove-overloads/remove-overloads.cjs

Please note in the case of you need to use as the parser; otherwise, the codemod won't be applied properly!

Note: Applying the codemod might break your code formatting, so please don't forget to run and/or after you've applied the codemod!

A few notes about how codemod works:

• Generally, we're looking for the lucky case, when the first parameter is an object expression and contains the "queryKey" or "mutationKey" property (depending on which hook/method call is being transformed). If this is the case, your code already matches the new signature, so the codemod won't touch it. 🎉
• If the condition above is not fulfilled, then the codemod will check whether the first parameter is an array expression or an identifier that references an array expression. If this is the case, the codemod will put it into an object expression, then it will be the first parameter.
• If object parameters can be inferred, the codemod will attempt to copy the already existing properties to the newly created one.
• If the codemod cannot infer the usage, then it will leave a message on the console. The message contains the file name and the line number of the usage. In this case, you need to do the migration manually.
• If the transformation results in an error, you will also see a message on the console. This message will notify you something unexpected happened, please do the migration manually.

Callbacks on useQuery (and QueryObserver) have been removed#

, and have been removed from Queries. They haven't been touched for Mutations. Please see this RFC for motivations behind this change and what to do instead.

The callback function only gets passed#

This streamlines how callbacks are invoked (the , and callbacks all only get the query passed as well), and it fixes some typing issues when callbacks get data transformed by .

- refetchInterval: number | false | ((data: TData | undefined, query: Query) => number | false | undefined) 
+ refetchInterval: number | false | ((query: Query) => number | false | undefined) 

- refetchInterval: number | false | ((data: TData | undefined, query: Query) => number | false | undefined) 
+ refetchInterval: number | false | ((query: Query) => number | false | undefined) 

You can still access data with , however, it will not be data that has been transformed by . If you need to access the transformed data, you can call the transformation again on .

The method has been removed from useQuery#

Previously, remove method used to remove the query from the queryCache without informing observers about it. It was best used to remove data imperatively that is no longer needed, e.g. when logging a user out.

But It doesn't make much sense to do this while a query is still active, because it will just trigger a hard loading state with the next re-render.

if you still need to remove a query, you can use

const queryClient = useQueryClient()
const query = useQuery({ queryKey, queryFn })

query.remove() 
queryClient.removeQueries({ queryKey }) 

const queryClient = useQueryClient()
const query = useQuery({ queryKey, queryFn })

query.remove() 
queryClient.removeQueries({ queryKey }) 

The minimum required TypeScript version is now 4.7#

Mainly because an important fix was shipped around type inference. Please see this TypeScript issue for more information.

The option has been removed from useQuery#

Previously, This function was used to indicate whether to use previous () or new data () as a resolved data for the query.

You can achieve the same functionality by passing a function to instead:

import { replaceEqualDeep } from '@tanstack/react-query'

- isDataEqual: (oldData, newData) => customCheck(oldData, newData) 
+ structuralSharing: (oldData, newData) => customCheck(oldData, newData) ? oldData : replaceEqualDeep(oldData, newData) 

import { replaceEqualDeep } from '@tanstack/react-query'

- isDataEqual: (oldData, newData) => customCheck(oldData, newData) 
+ structuralSharing: (oldData, newData) => customCheck(oldData, newData) ? oldData : replaceEqualDeep(oldData, newData) 

The deprecated custom logger has been removed#

Custom loggers were already deprecated in 4 and have been removed in this version. Logging only had an effect in development mode, where passing a custom logger is not necessary.

Supported Browsers#

We have updated our browserslist to produce a more modern, performant and smaller bundle. You can read about the requirements here.

Private class fields and methods#

TanStack Query has always had private fields and methods on classes, but they weren't really private - they were just private in . We now use ECMAScript Private class features, which means those fields are now truly private and can't be accessed from the outside at runtime.

Rename to #

Almost everyone gets wrong. It sounds like "the amount of time that data is cached for", but that is not correct.

does nothing as long as a query is still in use. It only kicks in as soon as the query becomes unused. After the time has passed, data will be "garbage collected" to avoid the cache from growing.

is referring to "garbage collect" time. It's a bit more technical, but also a quite well known abbreviation in computer science.

const MINUTE = 1000 * 60;

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
-      cacheTime: 10 * MINUTE, 
+      gcTime: 10 * MINUTE, 
    },
  },
})

const MINUTE = 1000 * 60;

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
-      cacheTime: 10 * MINUTE,
+      gcTime: 10 * MINUTE,
    },
  },
})

The option has been renamed to #

To make the option more framework-agnostic and avoid confusion with the established React function prefix "" for hooks and the "ErrorBoundary" component name, it has been renamed to to more accurately reflect its functionality.

TypeScript: is now the default type for errors instead of #

Even though in JavaScript, you can anything (which makes the most correct type), almost always, (or subclasses of ) are thrown. This change makes it easier to work with the field in TypeScript for most cases.

If you want to throw something that isn't an Error, you'll now have to set the generic for yourself:

useQuery<number, string>({
  queryKey: ['some-query'],
  queryFn: async () => {
    if (Math.random() > 0.5) {
      throw 'some error'
    }
    return 42
  },
})

useQuery<number, string>({
  queryKey: ['some-query'],
  queryFn: async () => {
    if (Math.random() > 0.5) {
      throw 'some error'
    }
    return 42
  },
})

For a way to set a different kind of Error globally, see the TypeScript Guide.

eslint rule is removed#

Since the only supported syntax now is the object syntax, this rule is no longer needed

Removed in favor of identity function#

We have removed the option and flag as they were doing mostly the same thing as and flag.

To achieve the same functionality as , we have added previous query as an argument to which accepts an identity function. Therefore you just need to provide an identity function to or use the included function from TanStack Query.

A note here is that would not receive in the function as argument. This is due to a dynamic nature of queries passed in the array, which may lead to a different shape of result from placeholder and queryFn.

import {
   useQuery,
+  keepPreviousData 
} from "@tanstack/react-query";

const {
   data,
-  isPreviousData, 
+  isPlaceholderData, 
} = useQuery({
  queryKey,
  queryFn,
- keepPreviousData: true, 
+ placeholderData: keepPreviousData 
});

import {
   useQuery,
+  keepPreviousData
} from "@tanstack/react-query";

const {
   data,
-  isPreviousData,
+  isPlaceholderData,
} = useQuery({
  queryKey,
  queryFn,
- keepPreviousData: true,
+ placeholderData: keepPreviousData
});

An identity function, in the context of TanStack Query, refers to a function that always returns its provided argument (i.e. data) unchanged.

useQuery({
  queryKey,
  queryFn,
  placeholderData: (previousData, previousQuery) => previousData, // identity function with the same behaviour as `keepPreviousData`
})

useQuery({
  queryKey,
  queryFn,
  placeholderData: (previousData, previousQuery) => previousData, // identity function with the same behaviour as `keepPreviousData`
})

There are some caveats to this change however, which you must be aware of:

• will always put you into state, while gave you the status of the previous query. That status could be if we have data fetched successfully and then got a background refetch error. However, the error itself was not shared, so we decided to stick with behavior of .

• gave you the timestamp of the previous data, while with , will stay at . This might be annoying if you want to show that timestamp continuously on screen. However you might get around it with .

  ts

  const [updatedAt, setUpdatedAt] = useState(0)
  
  const { data, dataUpdatedAt } = useQuery({
    queryKey: ['projects', page],
    queryFn: () => fetchProjects(page),
  })
  
  useEffect(() => {
    if (dataUpdatedAt > updatedAt) {
      setUpdatedAt(dataUpdatedAt)
    }
  }, [dataUpdatedAt])

  const [updatedAt, setUpdatedAt] = useState(0)
  
  const { data, dataUpdatedAt } = useQuery({
    queryKey: ['projects', page],
    queryFn: () => fetchProjects(page),
  })
  
  useEffect(() => {
    if (dataUpdatedAt > updatedAt) {
      setUpdatedAt(dataUpdatedAt)
    }
  }, [dataUpdatedAt])

Window focus refetching no longer listens to the event#

The event is used exclusively now. This is possible because we only support browsers that support the event. This fixes a bunch of issues as listed here.

Network status no longer relies on the property#

doesn't work well in Chromium based browsers. There are a lot of issues around false negatives, which lead to Queries being wrongfully marked as .

To circumvent this, we now always start with and only listen to and events to update the status.

This should reduce the likelihood of false negatives, however, it might mean false positives for offline apps that load via serviceWorkers, which can work even without an internet connection.

Removed custom prop in favor of custom instance#

In v4, we introduced the possibility to pass a custom to all react-query hooks. This allowed for proper isolation when using MicroFrontends.

However, is a react-only feature. All that does is give us access to the . We could achieve the same isolation by allowing to pass in a custom directly. This in turn will enable other frameworks to have the same functionality in a framework-agnostic way.

import { queryClient } from './my-client'

const { data } = useQuery(
  {
    queryKey: ['users', id],
    queryFn: () => fetch(...),
-   context: customContext 
  },
+  queryClient, 
)

import { queryClient } from './my-client'

const { data } = useQuery(
  {
    queryKey: ['users', id],
    queryFn: () => fetch(...),
-   context: customContext
  },
+  queryClient,
)

Removed in favor of #

In v4, we introduced the possibility to define the pages to refetch for infinite queries with the function.

However, refetching all pages might lead to UI inconsistencies. Also, this option is available on e.g. , but it only does something for infinite queries, not "normal" queries.

The v5 includes a new option for infinite queries to limit the number of pages to store in the query data and to refetch. This new feature handles the use cases initially identified for the page feature without the related issues.

New API#

The options you can pass to have been simplified. Queries and Mutations are always dehydrated (according to the default function implementation). To change this behaviour, instead of using the removed boolean options and you can implement the function equivalents or instead. To get the old behaviour of not hydrating queries/mutations at all, pass in .

- dehydrateMutations?: boolean 
- dehydrateQueries?: boolean 

- dehydrateMutations?: boolean
- dehydrateQueries?: boolean

Infinite queries now need a #

Previously, we've passed to the as , and you could assign a default value to the parameter in the function signature. This had the drawback of storing in the , which is not serializable.

Instead, you now have to pass an explicit to the infinite query options. This will be used as the for the first page:

useInfiniteQuery({
   queryKey,
-  queryFn: ({ pageParam = 0 }) => fetchSomething(pageParam), 
+  queryFn: ({ pageParam }) => fetchSomething(pageParam), 
+  initialPageParam: 0, 
   getNextPageParam: (lastPage) => lastPage.next,
})

useInfiniteQuery({
   queryKey,
-  queryFn: ({ pageParam = 0 }) => fetchSomething(pageParam),
+  queryFn: ({ pageParam }) => fetchSomething(pageParam),
+  initialPageParam: 0,
   getNextPageParam: (lastPage) => lastPage.next,
})

Manual mode for infinite queries has been removed#

Previously, we've allowed to overwrite the that would be returned from or by passing a value directly to or . This feature didn't work at all with refetches and wasn't widely known or used. This also means that is now required for infinite queries.

Returning from or now indicates that there is no further page available#

In v4, you needed to explicitly return to indicate that there is no further page available. We've widened this check to include .

No retries on the server#

On the server, now defaults to instead of . For prefetching, we have always defaulted to retries, but since queries that have enabled can now execute directly on the server as well (since React18), we have to make sure that we don't retry on the server at all.

has been changed to and has been changed to and has now been renamed to #

The status has been renamed to , and similarly the derived flag has been renamed to .

For mutations as well the has been changed from to and the flag has been changed to .

Lastly, a new derived flag has been added to the queries that is implemented as . This means that and have the same thing, but is deprecated now and will be removed in the next major version.

To understand the reasoning behind this change checkout the v5 roadmap discussion.

has been renamed to #

because it also hashes mutation keys and can be used inside the functions of and , which gets mutations passed.

The minimum required React version is now 18.0#

React Query v5 requires React 18.0 or later. This is because we are using the new hook, which is only available in React 18.0 and later. Previously, we have been using the shim provided by React.

The prop has been removed from QueryClientProvider#

You could previously use the property to share the first (and at least one) instance of the query client context across the window. This ensured that if TanStack Query was used across different bundles or microfrontends then they will all use the same instance of the context, regardless of module scoping.

With the removal of the custom context prop in v5, refer to the section on Removed custom context prop in favor of custom queryClient instance. If you wish to share the same query client across multiple packages of an application, you can directly pass a shared custom instance.

No longer using as the batching function in React and React Native#

Since the function is noop in React 18, it will no longer be automatically set as the batching function in .

If your framework supports a custom batching function, you can let TanStack Query know about it by calling .

For example, this is how the batch function is set in :

import { notifyManager } from '@tanstack/query-core'
import { batch } from 'solid-js'

notifyManager.setBatchNotifyFunction(batch)

import { notifyManager } from '@tanstack/query-core'
import { batch } from 'solid-js'

notifyManager.setBatchNotifyFunction(batch)

Hydration API changes#

To better support concurrent features and transitions we've made some changes to the hydration APIs. The component has been renamed to and the hook has been removed.

The no longer hydrates mutations, only queries. To hydrate mutations, use the low level API or the plugin.

Finally, as a technical detail, the timing for when queries are hydrated have changed slightly. New queries are still hydrated in the render phase so that SSR works as usual, but any queries that already exist in the cache are now hydrated in an effect instead (as long as their data is fresher than what is in the cache). If you are hydrating just once at the start of your application as is common, this wont affect you, but if you are using Server Components and pass down fresh data for hydration on a page navigation, you might notice a flash of the old data before the page immediately rerenders.

This last change is technically a breaking one, and was made so we don't prematurely update content on the existing page before a page transition has been fully committed. No action is required on your part.

- import { Hydrate } from '@tanstack/react-query'
+ import { HydrationBoundary } from '@tanstack/react-query'


- <Hydrate state={dehydratedState}>
+ <HydrationBoundary state={dehydratedState}>
  <App />
- </Hydrate>
+ </HydrationBoundary>

- import { Hydrate } from '@tanstack/react-query'
+ import { HydrationBoundary } from '@tanstack/react-query'


- <Hydrate state={dehydratedState}>
+ <HydrationBoundary state={dehydratedState}>
  <App />
- </Hydrate>
+ </HydrationBoundary>

Query defaults changes#

will now merge together all matching registrations instead of returning only the first matching registration.

As a result, calls to should now be ordered with increasing specificity. That is, registrations should be made from the most generic key to the least generic one.

For example:

+ queryClient.setQueryDefaults(['todo'], {   
+   retry: false,  
+   staleTime: 60_000,  
+ })  
queryClient.setQueryDefaults(['todo', 'detail'], {
+   retry: true,  
  retryDelay: 1_000,
  staleTime: 10_000,
})
- queryClient.setQueryDefaults(['todo'], { 
-   retry: false, 
-   staleTime: 60_000, 
- }) 

+ queryClient.setQueryDefaults(['todo'], {
+   retry: false,
+   staleTime: 60_000,
+ })  
queryClient.setQueryDefaults(['todo', 'detail'], {
+   retry: true,
  retryDelay: 1_000,
  staleTime: 10_000,
})
- queryClient.setQueryDefaults(['todo'], {
-   retry: false,
-   staleTime: 60_000,
- }) 

Note that in this specific example, was added to the registration to counteract it now inheriting from the more general registration. The specific changes needed to maintain exact behavior will vary depending on your defaults.

New Features 🚀#

v5 also comes with new features:

Simplified optimistic updates#

We have a new, simplified way to perform optimistic updates by leveraging the returned from :

const queryInfo = useTodos()
const addTodoMutation = useMutation({
  mutationFn: (newTodo: string) => axios.post('/api/data', { text: newTodo }),
  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
})

if (queryInfo.data) {
  return (
    <ul>
      {queryInfo.data.items.map((todo) => (
        <li key={todo.id}>{todo.text}</li>
      ))}
      {addTodoMutation.isPending && (
        <li key={String(addTodoMutation.submittedAt)} style={{ opacity: 0.5 }}>
          {addTodoMutation.variables}
        </li>
      )}
    </ul>
  )
}

const queryInfo = useTodos()
const addTodoMutation = useMutation({
  mutationFn: (newTodo: string) => axios.post('/api/data', { text: newTodo }),
  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
})

if (queryInfo.data) {
  return (
    <ul>
      {queryInfo.data.items.map((todo) => (
        <li key={todo.id}>{todo.text}</li>
      ))}
      {addTodoMutation.isPending && (
        <li key={String(addTodoMutation.submittedAt)} style={{ opacity: 0.5 }}>
          {addTodoMutation.variables}
        </li>
      )}
    </ul>
  )
}

Here, we are only changing how the UI looks when the mutation is running instead of writing data directly to the cache. This works best if we only have one place where we need to show the optimistic update. For more details, have a look at the optimistic updates documentation.

Limited, Infinite Queries with new maxPages option#

Infinite queries are great when infinite scroll or pagination are needed. However, the more pages you fetch, the more memory you consume, and this also slows down the query refetching process as all the pages are sequentially refetched.

Version 5 has a new option for infinite queries, which allows developers to limit the number of pages that are stored in the query data and subsequently refetched. You can adjust the value according to the UX and refetching performance you want to deliver.

Note that the infinite list must be bi-directional, which requires both and to be defined.

Infinite Queries can prefetch multiple pages#

Infinite Queries can be prefetched like regular Queries. Per default, only the first page of the Query will be prefetched and will be stored under the given QueryKey. If you want to prefetch more than one page, you can use the option. Read the prefetching guide for more information.

New option for #

See the useQueries docs for more details.

Experimental #

See the experimental_createPersister docs for more details.

Typesafe way to create Query Options#

See the TypeScript docs for more details.

new hooks for suspense#

With v5, suspense for data fetching finally becomes "stable". We've added dedicated , and hooks. With these hooks, will never be potentially on type level:

const { data: post } = useSuspenseQuery({
  // ^? const post: Post
  queryKey: ['post', postId],
  queryFn: () => fetchPost(postId),
})

const { data: post } = useSuspenseQuery({
  // ^? const post: Post
  queryKey: ['post', postId],
  queryFn: () => fetchPost(postId),
})

The experimental flag on the query hooks has been removed.

You can read more about them in the suspense docs.