Hooks for fetching, caching and updating asynchronous data in React

Become a Sponsor

Quick Features

• Transport, protocol & backend agnostic data fetching
• Auto Caching + Refetching (stale-while-revalidate, Window Refocus, Polling/Realtime)
• Parallel + Dependent Queries
• Mutations + Automatic Query Refetching
• Multi-layer Cache + Garbage Collection
• Load-More Pagination + Scroll Recovery
• React Suspense Support
• 

Examples

• Basic
• Custom Hooks
• Auto Refetching / Polling / Realtime
• Window Refocus Refetching
• Optimistic Updates
• Load-More Pagination
• Suspense CodeSandbox
• Playground CodeSandbox

Documentation

• Installation
• Queries
  • Query Keys
  • Query Variables
  • Dependent Queries
  • Caching & Invalidation
  • Pagination
  • Load-More/Infinite-Scroll Pagination
  • Scroll Restoration
  • Manual Querying
  • Retries
  • Retry Delay
  • Suspense Mode
• Mutations
  • Basic Mutations
  • Mutation Variables
  • Invalidate and Refetch Queries from Mutations
  • Query Updates from Mutations
• Manually or Optimistically Setting Query Data
• Displaying Background Fetching Loading States
• Displaying Global Background Fetching Loading State
• Window-Focus Refetching
• API
  • useQuery
  • useMutation
  • setQueryData
  • refetchQuery
  • refetchAllQueries
  • useIsFetching
  • useReactQueryConfig

Installation

$ npm i --save react-query
# or
$ yarn add react-query

Queries

To make a new query, call the useQuery hook with:

• A unique key for the query
• An asynchronous function (or similar then-able) to resolve the data

const info = useQuery('todos', fetchTodoList)

The unique key you provide is used internally for refetching, caching, deduping related queries.

This key can be whatever you'd like it to be as long as:

• It changes when your query should be requested again
• It is consistent across all instances of that specific query in your application

The query info returned contains all information about the query and can be easily destructured and used in your component:

function Todos() {
  const { data, isLoading, error } = useQuery('todos', fetchTodoList)

  return (
    <div>
      {isLoading ? (
        <span>Loading...</span>
      ) : error ? (
        <span>Error: {error.message}</span>
      ) : data ? (
        <ul>
          {data.map(todo => (
            <li key={todo.id}>{todo.title}</li>
          ))}
        </ul>
      ) : null}
    </div>
  )
}

Query Keys

Since React Query uses a query's unique key for essentially everything, it's important to tailor them so that will change with your query requirements. In other libraries like Zeit's SWR, you'll see the use of URL's and GraphQL query template strings to achieve this, but we believe at scale, this becomes prone to typos and errors. To relieve this issue, you can pass a tuple key with a string and object of variables to deterministically get the the same key.

Pro Tip: Variables passed in the key are automatically passed to your query function!

All of the following queries would result in using the same key:

useQuery(['todos', { status, page }])
useQuery(['todos', { page, status }])
useQuery(['todos', { page, status, other: undefined }])

Note: To aid you in your quest, if a query key is used that contains a ? (like todos?page=${page}&status=${status}), you will see a gentle console warning to use the above format instead.

Query Variables

To use external props, state, or variables in a query function, pass them as a variables in your query key! They will be passed through to your query function as the first parameter.

function Todos({ status }) {
  const { data, isLoading, error } = useQuery(
    ['todos', { status, page }],
    fetchTodoList // This is the same as `fetchTodoList({ status, page })`
  )
}

Whenever a query's key changes, the query will automatically update:

function Todos() {
  const [page, setPage] = useState(0)

  const { data, isLoading, error } = useQuery(
    ['todos', { page }],
    fetchTodoList
  )

  const onNextPage = () => {
    setPage(page => page + 1)
  }

  return (
    <>
      {/* ... */}
      <button onClick={onNextPage}>Load next page</button>
    </>
  )
}

Dependent Queries

React Query makes it easy to make queries that depends on other queries for both:

• Parallel Queries (avoiding waterfalls) and
• Serial Queries (when a piece of data is required for the next query to happen.

To do this effectively, you can use the following 2 approaches:

Pass a falsey query key

If a query isn't ready to be requested yet, just pass a falsey value as the query key:

const { data: user } = useQuery(['user', { userId }])
const { data: projects } = useQuery(user && ['projects', { userId: user.id }]) // User is `null`, so the query key will be falsey

Use a query key function

If a function is passed, the query will not execute until the function can be called without throwing:

const { data: user } = useQuery(['user', { userId }])
const { data: projects } = useQuery(() => ['projects', { userId: user.id }]) // This will throw until `user` is available

Mix them together!

const [ready, setReady] = React.useState(false)
const { data: user } = useQuery(ready && ['user', { userId }]) // Wait for ready
const { data: projects } = useQuery(
  () => ready && ['projects', { userId: user.id }] // Wait for ready and user.id

Caching & Invalidation

React Query caching is automatic out of the box. It uses a stale-while-revalidate in-memory caching model across queries along with query deduping to to always ensure a query's data is only stored once even if that query is used multiple times across your application.

At a glance:

• Caching is automatic and aggressive by default.
• The cache is keyed on unique query + variables combinations.
• By default query results become stale immediately after a successful fetch. This can be configured using the staleTime option at both the global and query-level)
• Stale queries are automatically refetched whenever their query keys change (this includes variables used in query key tuples) or when new usages/instances of the query are mounted.
• By default query results are always cached when in use.
• If a query is no longer being used, it becomes inactive and by default is cached in the background for 5 minutes. This time can be configured using the cacheTime option at both the global and query-level)
• After a query is inactive for the time specified via the cacheTime option (defaults to 5 minutes), the query is deleted and garbage collected.

Did You Know? - Because React Query doesn't use document normalization in its cache (made popular with libraries like Apollo and Redux-Query), it eliminates a whole range of common issues with caching like incorrect data merges, failed cache reads/writes, and imperative maintenance of the cache.

Pagination

If all you need is page-based pagination, where the previous set of data is replaced with a new one, this section is not applicable to your use-case. For that, you can increment the page variable and pass it to your query via variables.

However, if your app needs to add more data to the list along with existing one (for example, infinite loading), React Query provides you with a way to fetch additional data without deleting the current data. Let's use page-based pagination for simplicity, but assume that we want to append new todo items at the end of the list.

function Todos() {
  const { data, isLoading, error, refetch, isFetching } = useQuery(
    ['todos', { page: 1 }],
    fetchTodoList
  )

  const onFetchMore = () => {
    refetch({
      variables: { page: data.pagination.nextPage },
      merge: (prev, next) => ({
        ...next,
        // Merge the new todos with the existing ones
        todos: [...prev.todos, ...next.todos],
      }),
    })
  }

  return isLoading ? (
    <span>Loading...</span>
  ) : error ? (
    <span>Error: {error.message}</span>
  ) : data ? (
    <>
      <ul>
        {data.todos.map(todo => (
          <li key={todo.id}>{todo.title}</li>
        ))}
      </ul>
      {data.pagination.hasMore && (
        <button disabled={isFetching} onClick={onFetchMore}>
          {isFetching ? 'Loading more todos...' : 'Load more todos'}
        </button>
      )}
    </>
  ) : null
}

Load-More/Infinite-Scroll Pagination

Rendering paginated lists that can "load more" data or "infinite scroll" is a common UI pattern. React Query supports some useful features for querying these types of lists. Let's assume we have an API that returns pages of todos 3 at a time based on a cursor index:

fetch('/api/projects?cursor=0'
// { data: [...], nextId: 3}
fetch('/api/projects?cursor=3'
// { data: [...], nextId: 6}
fetch('/api/projects?cursor=6'
// { data: [...], nextId: 9}

Using the nextId value in each page's response, we can configure useQuery to fetch more pages as needed:

• Configure your query function to use optional pagination variables. We'll send through the nextId as the cursor for the next page request
• Set the paginated option to true
• Define a getCanFetchMore option to know if there is more data to load (it receives the lastPage and allPages as parameters)

import { useQuery } from 'react-query'

function Todos() {
  const {
    data: pages,
    isLoading,
    isFetching,
    isFetchingMore,
    fetchMore,
    canFetchMore,
  } = useQuery(
    'todos',
    ({ nextId } = {}) => fetch('/api/projects?cursor=' + (nextId || 0)),
    {
      paginated: true,
      getCanFetchMore: (lastPage, allPages) => next.nextId,
    }
  )

  // ...
}

You'll notice a few new things now:

• data is now an array of pages that contain query results, instead of the query results themselves
• A fetchMore function is now available
• A canFetchMore boolean is now available
• An isFetchingMore boolean is now available

These can now be used to render a "load more" list (this example uses an offset key):

import { useQuery } from 'react-query'

function Todos() {
  const {
    data: pages,
    isLoading,
    isFetching,
    isFetchingMore,
    fetchMore,
    canFetchMore,
  } = useQuery(
    'projects',
    ({ offset } = {}) => fetch('/api/projects?offset=' + (offset || 0)),
    {
      paginated: true,
      getCanFetchMore: (lastPage, allPages) => next.nextId,
    }
  )

  const loadMore = async () => {
    try {
      // Get the last page
      const lastPage = data[data.length - 1]
      // Get the last item's ID
      const lastItemId = lastPage[lastPage.length - 1].id
      // Fetch more with the offset ID + 1
      await fetchMore({
        offset: lastItemId + 1,
      })
    } catch {}
  }

  return isLoading ? (
    <p>Loading...</p>
  ) : data ? (
    <>
      {data.map((page, i) => (
        <React.Fragment key={i}>
          {page.data.map(project => (
            <p key={project.id}>{project.name}</p>
          ))}
        </React.Fragment>
      ))}
      <div>
        {canFetchMore ? (
          <button onClick={loadMore} disabled={isFetchingMore}>
            {isFetchingMore ? 'Loading more...' : 'Load More'}
          </button>
        ) : (
          'Nothing more to fetch.'
        )}
      </div>
      <div>
        {isFetching && !isFetchingMore ? 'Background Updating...' : null}
      </div>
    </>
  ) : null
}

What happens when a paginated query needs to be refetched?**

When a paginated query becomes stale and needs to be refetched, each page is fetched individually with the same variables that were used to request it originally. If a paginated query's results are ever removed from the cache, the pagination restarts at the initial state with a single page being requested.

Scroll Restoration

Out of the box, "scroll restoration" Just Works™️ in React Query. The reason for this is that query results are cached and retrieved synchronously when rendered. As long as a query is cached and has not been garbage collected, you should never experience problems with scroll restoration.

Manual Querying

If you ever want to disable a query from automatically running, you can use the manual = true option. When manual is set to true:

• The query will not automatically refetch due to changes to their query function or variables.
• The query will not automatically refetch due to refetchQueries options in other queries or via useRefetchQuery calls.

function Todos() {
  const { data, isLoading, error, refetch, isFetching } = useQuery(
    'todos',
    fetchTodoList,
    {
      manual: true,
    }
  )

  return (
    <>
      <button onClick={() => refetch()}>Fetch Todos</button>

      {isLoading ? (
        <span>Loading...</span>
      ) : error ? (
        <span>Error: {error.message}</span>
      ) : data ? (
        <>
          <ul>
            {data.map(todo => (
              <li key={todo.id}>{todo.title}</li>
            ))}
          </ul>
        </>
      ) : null}
    </>
  )
}

Pro Tip: Don't use manual for dependent queries. Use Dependent Queries instead!

Retries

When a useQuery query fails (the function throws an error), React Query will automatically retry the query if that query's request has not reached the max number of consecutive retries (defaults to 3).

You can configure retries both on a global level and an individual query level.

• Setting retry = false will disable retries
• Setting retry = 6 will retry failing requests 6 times before showing the final error thrown by the function
• Setting retry = true will infinitely retry failing requests.

import { useReactQueryConfig } from 'react-query'

// Turn off retries for all queries
useReactQueryConfig({
  retry: false,
})

// Make specific query retry a certain number of times
const { data, isLoading, error } = useQuery(
  ['todos', { page: 1 }],
  fetchTodoList,
  {
    retry: 10, // Will retry failed requests 10 times before displaying an error
  }
)

Retry Delay

By default, retries in React Query do not happen immediately after a request fails. As is standard, a back-off delay is gradually applied to each retry attempt.

The default retryDelay is set to double (starting at 1000ms) with each attempt, but not exceed 30 seconds:

// Configure for all queries
import { useReactQueryConfig } from 'react-query'

const config = {
  retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 30000),
}

function App() {
  useReactQueryConfig(config)

  return <Stuff />
}

Though it is not recommended, you can obviously override the retryDelay function/integer in both the Provider and individual query options. If set to an integer instead of a function the delay will always be the same amount of time:

const { data, isLoading, error } = useQuery('todos', fetchTodoList, {
  retryDelay: 10000, // Will always wait 1000ms to retry, regardless of how many retries
})

Suspense Mode

React Query can also be used with React's new Suspense for Data Fetching API's. To enable this mode, you can set either the global or query level config's suspense option to true:

const { useReactQueryConfig, useQuery } from 'react-query'

// Enable for all queries by default
useReactQueryConfig({
  suspense: true
})

// Enable for an individual query
useQuery(queryKey, queryFn, { suspense: true })

When using suspense mode, isLoading and error states will be replaced by usage of the React.Suspense component (including the use of the fallback prop and React error boundaries for catching errors. Please see the Suspense Example for more information on how to set up suspense mode.

Mutations

Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects. For this purpose, React Query exports a useMutation hook.

Basic Mutations

Assuming the server implements a ping mutation, that returns "pong" string, here's an example of the most basic mutation:

const PingPong = () => {
  const [mutate, { data, isLoading, error }] = useMutation(pingMutation)

  const onPing = async () => {
    try {
      const data = await mutate()
      console.log(data)
      // { ping: 'pong' }
    } catch {
      // Uh oh, something went wrong
    }
  }
  return <button onClick={onPing}>Ping</button>
}

Mutations without variables are not that useful, so let's add some variables to closer match reality.

Mutation Variables

To pass variables to your mutate function, call mutate with an object.

const CreateTodo = () => {
  const [title, setTitle] = useState('')
  const [mutate] = useMutation(createTodo)

  const onCreateTodo = async e => {
    // Prevent the form from refreshing the page
    e.preventDefault()

    try {
      await mutate({ title })
      // Todo was successfully created
    } catch (error) {
      // Uh oh, something went wrong
    }
  }

  return (
    <form onSubmit={onCreateTodo}>
      <input
        type="text"
        value={title}
        onChange={e => setTitle(e.target.value)}
      />
      <br />
      <button type="submit">Create Todo</button>
    </form>
  )
}

Even with just variables, mutations aren't all that special, but when used with the refetchQueries and updateQuery options, they become a very powerful tool.

Invalidate and Refetch Queries from Mutations

When a mutation succeeds, it's likely that other queries in your application need to update. Where other libraries that use normalized caches would attempt to update locale queries with the new data imperatively, React Query avoids the pitfalls that come with normalized caches and prescribes atomic updates instead of partial cache manipulation.

For example, assume we have a mutation to post a new todo:

const [mutate] = useMutation(postTodo)

When a successful postTodo mutation happens, we likely want all todos queries to get refetched to show the new todo item. To do this, you can use the refetchQueries option when calling a mutation's mutate function.

// When this mutation succeeds, any queries with the `todos` or `reminders` query key will be refetched
mutate(newTodo, { refetchQueries: ['todos', 'reminders'], })

// The 3 queries below will be refetched when the mutation above succeeds
const todoListQuery = useQuery('todos', fetchTodoList)
const todoListQuery = useQuery(['todos', { page: 1 }, fetchTodoList)
const remindersQuery = useQuery('reminders', fetchReminders)

You can even refetch queries with specific variables by passing a query key tuple to refetchQueries:

mutate(newTodo, { refetchQueries: [['todos', { status: 'done' }]] })

// The query below will be refetched when the mutation above succeeds
const todoListQuery = useQuery(['todos', { status: 'done' }], fetchTodoList)
// However, the following query below will NOT be refetched
const todoListQuery = useQuery('todos', fetchTodoList)

If you want to only refetch todos queries that don't have variables, you can pass a tuple with variables set to false:

mutate(newTodo, { refetchQueries: [['todos', false]] })

// The query below will be refetched when the mutation above succeeds
const todoListQuery = useQuery(['todos'], fetchTodoList)
// However, the following query below will NOT be refetched
const todoListQuery = useQuery(['todos', { status: 'done' }], fetchTodoList)

If you prefer that the promise returned from mutate() only resolves after any refetchQueries have been refetched, you can pass the waitForRefetchQueries = true option to mutate:

const [mutate] = useMutation(addTodo, { refetchQueries: ['todos'] })

const run = async () => {
  try {
    await mutate(todo, { waitForRefetchQueries: true })
    console.log('I will only log after all refetchQueries are done refetching!')
  } catch {}
}

It's important to note that refetchQueries by default will only happen after a successful mutation (the mutation function doesn't throw an error). If you would like to refetch the refetchQueries regardless of this, you can set refetchQueriesOnFailure to true in your mutate options:

const [mutate] = useMutation(addTodo, { refetchQueries: ['todos'] })

const run = async () => {
  try {
    await mutate(todo, { refetchQueriesOnFailure: true })
    // Even if the above mutation fails, any `todos` queries will still be refetched.
  } catch {}
}

Query Updates from Mutations

When dealing with mutations that update objects on the server, it's common for the new object to be automatically returned in the response of the mutation. Instead of invalidating any queries for that item and wasting a network call to refetch them again, we can take advantage of the object returned by the mutation function and update any query responses with that data that match that query using the updateQuery option:

const [mutate] = useMutation(editTodo)

mutate(
  {
    id: 5,
    name: 'Do the laundry',
  },
  {
    updateQuery: ['todo', { id: 5 }],
  }
)

// The query below will be updated with the response from the mutation above when it succeeds
const { data, isLoading, error } = useQuery(['todo', { id: 5 }], fetchTodoByID)

Manually or Optimistically Setting Query Data

In rare circumstances, you may want to manually update a query's response before it has been refetched. To do this, you can use the exported setQueryData function:

import { setQueryData } from 'react-query'

// Full replacement
setQueryData(['todo', { id: 5 }], newTodo)

// or functional update
setQueryData(['todo', { id: 5 }], previous => ({ ...previous, status: 'done' }))

Most importantly, when manually setting a query response, it naturally becomes out-of-sync with it's original source. To ease this issue, setQueryData automatically triggers a background refresh of the query after it's called to ensure it eventually synchronizes with the original source.

Should you choose that you do not want to refetch the query automatically, you can set the shouldRefetch option to false:

import { setQueryData } from 'react-query'

// Mutate, but do not automatically refetch the query in the background
setQueryData(['todo', { id: 5 }], newTodo, {
  shouldRefetch: false,
})

Displaying Background Fetching Loading States

A query's isLoading boolean is usually sufficient to show the initial hard-loading state for a query, but sometimes you may want to display a more subtle indicator that a query is refetching in the background. To do this, queries also supply you with an isFetching boolean that you can use to show that it's in a fetching state:

function Todos() {
  const { data: todos, isLoading, isFetching } = useQuery('todos', fetchTodos)

  return isLoading ? (
    <span>Loading...</span>
  ) : todos ? (
    <>
      {isFetching ? <div>Refreshing...</div> : null}

      <div>
        {todos.map(todo => (
          <Todo todo={todo} />
        ))}
      </div>
    </>
  ) : null
}

Displaying Global Background Fetching Loading State

In addition to individual query loading states, if you would like to show a global loading indicator when any queries are fetching (including in the background), you can use the useIsFetching hook:

import { useIsFetching } from 'react-query'

function GlobalLoadingIndicator() {
  const isFetching = useIsFetching()

  return isFetching ? (
    <div>Queries are fetching in the background...</div>
  ) : null
}

Window-Focus Refetching

If a user leaves your application and returns to stale data, you may want to trigger an update in the background to update any stale queries. Thankfully, React Query does this automatically for you, but if you choose to disable it, you can use the useReactQueryConfig's refetchAllOnWindowFocus option to disable it:

useReactQueryConfig({ refetchAllOnWindowFocus: false })

API

useQuery

const {
  data,
  error,
  isFetching,
  isCached,
  failureCount,
  isLoading,
  refetch,
  // with pagination mode enabled
  isFetchingMore,
  canFetchMore,
  fetchMore,
} = useQuery(queryKey, queryFn, {
  manual,
  pagination,
  getCanFetchMore,
  staleTime,
  retry,
  retryDelay,
  suspense,
})

Options

• queryKey: String | [String, Variables: Object] | falsey | Function => queryKey
  • Required
  • The query key to use for this query.
  • If a string is passed, it will be used as the query key
  • If a [String, Object] tuple is passed, they will be serialized into a stable query key. See Query Keys for more information.
  • If a falsey value is passed, the query will be disabled and not run automatically.
  • If a function is passed, it should resolve to any other valid query key type. If the function throws, the query will be disabled and not run automatically.
  • The query will automatically update when this key changes (if the key is not falsey and if manual is not set to true)
  • Variables: Object
    • If a tuple with variables is passed, this object should be serializable.
    • Nested arrays and objects are supported
    • The order of object keys is sorted to be stable before being serialized into the query key
• queryFn: Function(variables) => Promise(data/error)
  • Required
  • The function that the query will use to request data
  • Optionally receives the variables object passed from either the query key tuple (useQuery(['todos', variables], queryFn)) or the refetch method's variables option refetch({ variables })
  • Must return a promise that will either resolves data or throws an error.
• pagination: Boolean
  • Set this to true to enable pagination mode
  • In this mode, new pagination utilities are returned from useQuery and data becomes an array of page results
• manual: Boolean
  • Set this to true to disable automatic refetching when the query mounts or changes query keys.
  • To refetch the query, use the refetch method returned from the useQuery instance.
• getCanFetchMore: Function(lastPage, allPages) => Boolean
  • Required if using pagination mode
  • When using pagination mode, this function should return true if there is more data than can be fetched.
• retry: Boolean | Int
  • If false, failed queries will not retry by default
  • If true, failed queries will retry infinitely
  • If set to an Int, eg. 3, failed queries will retry until the failed query count meets that number
• retryDelay: Function(retryAttempt: Int) => Int
  • This function receives a retryAttempt integer and returns the delay to apply before the next attempt in milliseconds
  • A function like attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000) applies exponential backoff
  • A function like attempt => attempt * 1000 applies linear backoff.
• staleTime: Int
  • The time in milliseconds that cache data remains fresh. After a successful cache update, that cache data will become stale after this duration
• cacheTime: Int
  • The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration.
• refetchInterval: false | Integer
  • Optional
  • If set to a number, all queries will continuously refetch at this frequency in milliseconds
• suspense: Boolean
  • Optional
  • Set this to true to enable suspense mode.
  • When true, useQuery will suspend when isLoading would normally be true
  • When true, useQuery will throw runtime errors when error would normally be truthy

Returns

• data: null | Any
  • Defaults to null
  • The last successfully resolved data for the query.
• error: null | Error
  • The error object for the query, if an error was thrown.
• isLoading: Boolean
  • Will be true if the query is both fetching and does not have any cached data to display.
• isFetching: Boolean
  • Will be true if the query is currently fetching, including background fetching.
• isCached: Boolean
  • Will be true if the query's response is currently cached.
• failureCount: Integer
  • The failure count for the query.
  • Incremented every time the query fails.
  • Reset to 0 when the query succeeds.
• refetch: Function({ variables: Object, merge: Function, disableThrow: Boolean })
  • A function to manually refetch the query.
  • Supports custom variables (useful for "fetch more" calls)
  • Supports custom data merging (useful for "fetch more" calls)
  • Set disableThrow to true to disable this function from throwing if an error is encountered.
• isFetchingMore: Boolean
  • If using pagination mode, this will be true when fetching more results using the fetchMore function.
• canFetchMore: Boolean
  • If using pagination mode, this will be true if there is more data to be fetched (known via the required getCanFetchMore option function)
• fetchMore: Function(variables) => Promise
  • If using pagination mode, this function allows you to fetch the next "page" of results.
  • variables should be an object that is passed to your query function to retrieve the next page of results

useMutation

const [mutate, { data, isLoading, error }] = useMutation(mutationFn, {
  refetchQueries,
  refetchQueriesOnFailure,
})

const promise = mutate(variables, { updateQuery, waitForRefetchQueries })

Options

• mutationFn: Function(variables) => Promise
  • Required
  • A function that performs an asynchronous task and returns a promise
• refetchQueries: Array<QueryKey>
  • Optional
  • When the mutation succeeds, these queries will be automatically refetched
  • Must be an array of query keys, eg. ['todos', ['todo', { id: 5 }], 'reminders']
• refetchQueriesOnFailure: Boolean
  • Defaults to false
  • Set this to true if you want refetchQueries to be refetched regardless of the mutation succeeding.
• variables: any
  • Optional
  • The variables object to pass tot he mutationFn
• updateQuery: QueryKey
  • Optional
  • The query key for the individual query to update with the response from this mutation.
  • Suggested use is for update mutations that regularly return the updated data with the mutation. This saves you from making another unnecessary network call to refetch the data.
• waitForRefetchQueries: Boolean
  • Optional
  • If set to true, the promise returned by mutate() will not resolve until refetched queries are resolved as well.

Returns

• mutate: Function(variables, { updateQuery })
  • The mutation function you can call with variables to trigger the mutation and optionally update a query with its response.
• data: null | Any
  • Defaults to null
  • The last successfully resolved data for the query.
• error: null | Error
  • The error object for the query, if an error was thrown.
• isLoading: Boolean
  • Will be true if the query is both fetching and does not have any cached data
• promise: Promise
  • The promise that is returned by the mutationFn

setQueryData

setQueryData is a function for imperatively updating the response of a query. By default, this function also triggers a background refetch to ensure that the data is eventually consistent with the remote source, but this can be disabled.

import { setQueryData } from 'react-query'

const maybePromise = setQueryData(queryKey, data, { shouldRefetch })

Options

• queryKey: QueryKey
  • Required
  • The query key for the individual query to update with new data.
• data: any | Function(old) => any
  • Required
  • Must either be the new data or a function that receives the old data and returns the new data
• shouldRefetch: Boolean
  • Optional
  • Defaults to true
  • Set this to false to disable the automatic background refetch from happening

Returns

• maybePromise: undefined | Promise
  • If shouldRefetch is true, a promise is returned that will either resolve when the query refetch is complete or will reject if the refetch fails (after its respective retry configurations is done).

refetchQuery

refetchQuery is a function for imperatively triggering a refetch of either:

• A group of queries
• A single query

By default, it will only refetch stale queries, but the force option can be used to refetch all queries, including non-stale ones.

import { refetchQuery } from 'react-query'

const promise = refetchQuery(queryKey, { force })

Options

• queryKey: QueryKey
  • Required
  • The query key for the query or query group to refetch.
  • If a single string is passed, any queries using that string or any tuple key queries that include that string (eg. passing todos would refetch both todos and ['todos', { status: 'done' }]).
  • If a tuple key is passed, only the exact query with that key will be refetched (eg. ['todos', { status: 'done' }] will only refetch queries with that exact key)
  • If a tuple key is passed with the variables slot set to false, then only queries that match the string key and have no variables will be refetched (eg. ['todos', false] would only refetch todos and not ['todos', { status: 'done' }])
• force: Boolean
  • Optional
  • Set this to true to force all queries to refetch instead of only stale ones.

Returns

• promise: Promise
  • A promise is returned that will either resolve when all refetch queries are complete or will reject if any refetch queries fail (after their respective retry configurations are done).

refetchAllQueries

refetchAllQueries is a function for imperatively triggering a refetch of all queries. By default, it will only refetch stale queries, but the force option can be used to refetch all queries, including non-stale ones.

import { refetchAllQueries } from 'react-query'

const promise = refetchAllQueries({ force, includeInactive })

Options

• force: Boolean
  • Optional
  • Set this to true to force all queries to refetch instead of only stale ones.
• includeInactive: Boolean
  • Optional
  • Set this to true to also refetch inactive queries.
  • Overrides the force option to be true, regardless of it's value.

Returns

• promise: Promise
  • A promise is returned that will either resolve when all refetch queries are complete or will reject if any refetch queries fail (after their respective retry configurations are done).

useIsFetching

useIsFetching is an optional hook that returns true if any query in your application is loading for fetching in the background (useful for app-wide loading indicators)

import { useIsFetching } from 'react-query'

const isFetching = useIsFetching()

Returns

• isFetching: Boolean
  • Will be true if any query in your application is loading or fetching in the background

useReactQueryConfig

useReactQueryConfig is optional and can be used to define defaults for all instances of useQuery through your app:

import { useReactQueryConfig } from 'react-query'

useReactQueryConfig({
  retry: 3,
  retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 30000),
  staleTime: 0,
  cacheTime: 5 * 60 * 1000,
  refetchAllOnWindowFocus: true,
  refetchInterval: false,
  suspense: false,
})

Options

For a description of all options, please see the useQuery hook.

Returns

This hook does not return anything

Example

const config = {
  // These are the default config options for the useReactQueryConfig
  retry: 3,
  retryDelay: attempt =>
    Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000),
  staleTime: 10 * 1000, // 10 seconds
  invalidCacheTime: 10 * 1000, // 10 seconds
}

function App() {
  useReactQueryConfig({
    retry: 4
  })

  return </>
}