📄 tanstack/query/v4/docs/framework/react/reference/hydration

dehydrate creates a frozen representation of a cache that can later be hydrated with Hydrate, useHydrate, or hydrate. This is useful for passing prefetched queries from server to client or persisting queries to localStorage or other persistent locations. It only includes currently successful queries by default.

tsx

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

const dehydratedState = dehydrate(queryClient, {
  shouldDehydrateQuery,
})


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

const dehydratedState = dehydrate(queryClient, {
  shouldDehydrateQuery,
})

Options

client: QueryClient
- Required
- The queryClient that should be dehydrated
options: DehydrateOptions
- Optional
- dehydrateMutations: boolean
  - Optional
  - Whether or not to dehydrate mutations.
- dehydrateQueries: boolean
  - Optional
  - Whether or not to dehydrate queries.
- shouldDehydrateMutation: (mutation: Mutation) => boolean
  - Optional
  - This function is called for each mutation in the cache
  - Return true to include this mutation in dehydration, or false otherwise
  - The default version only includes paused mutations
  - If you would like to extend the function while retaining the previous behavior, import and execute defaultShouldDehydrateMutation as part of the return statement
- shouldDehydrateQuery: (query: Query) => boolean
  - Optional
  - This function is called for each query in the cache
  - Return true to include this query in dehydration, or false otherwise
  - The default version only includes successful queries, do shouldDehydrateQuery: () => true to include all queries
  - If you would like to extend the function while retaining the previous behavior, import and execute defaultShouldDehydrateQuery as part of the return statement

Returns

dehydratedState: DehydratedState
- This includes everything that is needed to hydrate the queryClient at a later point
- You should not rely on the exact format of this response, it is not part of the public API and can change at any time
- This result is not in serialized form, you need to do that yourself if desired

### limitations

Some storage systems (such as browser Web Storage API ) require values to be JSON serializable. If you need to dehydrate values that are not automatically serializable to JSON (like Error or undefined), you have to serialize them for yourself. Since only successful queries are included per default, to also include Errors, you have to provide shouldDehydrateQuery, e.g.:

tsx

// server
const state = dehydrate(client, { shouldDehydrateQuery: () => true }) // to also include Errors
const serializedState = mySerialize(state) // transform Error instances to objects

// client
const state = myDeserialize(serializedState) // transform objects back to Error instances
hydrate(client, state)


// server
const state = dehydrate(client, { shouldDehydrateQuery: () => true }) // to also include Errors
const serializedState = mySerialize(state) // transform Error instances to objects

// client
const state = myDeserialize(serializedState) // transform objects back to Error instances
hydrate(client, state)

hydrate
-------

hydrate adds a previously dehydrated state into a cache.

tsx

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

hydrate(queryClient, dehydratedState, options)


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

hydrate(queryClient, dehydratedState, options)

Options

client: QueryClient
- Required
- The queryClient to hydrate the state into
dehydratedState: DehydratedState
- Required
- The state to hydrate into the client
options: HydrateOptions
- Optional
- defaultOptions: DefaultOptions
  - Optional
  - mutations: MutationOptions The default mutation options to use for the hydrated mutations.
  - queries: QueryOptions The default query options to use for the hydrated queries.
- context?: React.Context<QueryClient | undefined>
  - Use this to use a custom React Query context. Otherwise, defaultContext will be used.

### Limitations

If the queries included in dehydration already exist in the queryCache, hydrate does not overwrite them and they will be silently discarded.

useHydrate
----------

useHydrate adds a previously dehydrated state into the queryClient that would be returned by useQueryClient(). If the client already contains data, the new queries will be intelligently merged based on update timestamp.

tsx

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

useHydrate(dehydratedState, options)


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

useHydrate(dehydratedState, options)

Options

dehydratedState: DehydratedState
- Required
- The state to hydrate
options: HydrateOptions
- Optional
- defaultOptions: QueryOptions
  - The default query options to use for the hydrated queries.
- context?: React.Context<QueryClient | undefined>
  - Use this to use a custom React Query context. Otherwise, defaultContext will be used.

Hydrate
-------

Hydrate wraps useHydrate into component. Can be useful when you need hydrate in class component or need hydrate on same level where QueryClientProvider rendered.

tsx

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

function App() {
  return <Hydrate state={dehydratedState}>...</Hydrate>
}


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

function App() {
  return <Hydrate state={dehydratedState}>...</Hydrate>
}

Options

state: DehydratedState
- The state to hydrate
options: HydrateOptions
- Optional
- defaultOptions: QueryOptions
  - The default query options to use for the hydrated queries.
- context?: React.Context<QueryClient | undefined>
  - Use this to use a custom React Query context. Otherwise, defaultContext will be used.

Edit on GitHub

useQueryErrorResetBoundary

ESLint Plugin Query

Partners Become a Partner

[###### Want to Skip the Docs?

Query.gg - The Official React Query Course
\

“If you’re serious about *really* understanding React Query, there’s no better way than with query.gg”—Tanner Linsley

Learn More](https://query.gg/?s=tanstack)

You are currently reading v4 docs. Redirect to latest version?

Latest Hide

scarf analytics