Queries

Query Basics

In React Query, a query is a declarative dependency on some asynchronous source of data. A query can be used with any Promise based method (including GET and POST methods) to fetch data from a server. If your method modifies data on the server, we recommend using Mutations instead.

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

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

1 import { useQuery } from 'react-query'
2 
3 function App() {
4   const info = useQuery('todos', fetchTodoList)
5 }

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

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

1 function Todos() {
2   const { isLoading, isError, data, error } = useQuery('todos', fetchTodoList)
3 
4   if (isLoading) {
5     return <span>Loading...</span>
6   }
7 
8   if (isError) {
9     return <span>Error: {error.message}</span>
10   }
11 
12   // also status === 'success', but "else" logic works, too
13   return (
14     <ul>
15       {data.map(todo => (
16         <li key={todo.id}>{todo.title}</li>
17       ))}
18     </ul>
19   )
20 }

If booleans aren't your thing, you can also use the status string to do the same:

1 function Todos() {
2   const { status, data, error } = useQuery('todos', fetchTodoList)
3 
4   if (status === 'loading') {
5     return <span>Loading...</span>
6   }
7 
8   if (status === 'error') {
9     return <span>Error: {error.message}</span>
10   }
11 
12   // also status === 'success', but "else" logic works, too
13   return (
14     <ul>
15       {data.map(todo => (
16         <li key={todo.id}>{todo.title}</li>
17       ))}
18     </ul>
19   )
20 }

Query Keys

At its core, React Query manages query caching for you based on query keys. Query keys can be as simple as a string, or as complex as an array or nested object of values. As long as the key is serializable, and unique to the query's data, you can use it!

If you're learning React Query still, we suggest starting with using strings and arrays with strings/numbers, then working your way up to using more complex query keys.

String-Only Query Keys

The simplest form of a key is actually not an array, but an individual string. When a string query key is passed, it is converted to an array internally with the string as the only item in the query key. This format is useful for:

• Generic List/Index resources
• Non-hierarchical resources

1 // A list of todos
2 useQuery('todos', ...) // queryKey === ['todos']
3 
4 // Something else, whatever!
5 useQuery('somethingSpecial', ...) // queryKey === ['somethingSpecial']

Array Keys

When a query needs more information to uniquely describe its data, you can use an array with a string and any number of serializable objects to describe it. This is useful for:

• Specific resources
  • It's common to pass an ID, index, or other primitive
• Queries with additional parameters
  • It's common to pass an object of additional options

1 // An individual todo
2 useQuery(['todo', 5], ...)
3 // queryKey === ['todo', 5]
4 
5 // And individual todo in a "preview" format
6 useQuery(['todo', 5, { preview: true }], ...)
7 // queryKey === ['todo', 5, { preview: true }]
8 
9 // A list of todos that are "done"
10 useQuery(['todos', { type: 'done' }], ...)
11 // queryKey === ['todos', { type: 'done' }]

Query Keys are serialized deterministically!

This means that no matter the order of keys in objects, all of the following queries would result in the same final query key of ['todos', { page, status }]:

1 useQuery(['todos', { status, page }], ...)
2 useQuery(['todos', { page, status }], ...)
3 useQuery(['todos', { page, status, other: undefined }], ...)

The following query keys, however, are not equal. Array item order matters!

1 useQuery(['todos', status, page], ...)
2 useQuery(['todos', page, status], ...)
3 useQuery(['todos', undefined, page, status], ...)

Query Key Variables

To use external props, state, or variables in a query function, it's easiest to pass them as items in your array query keys! All query keys get passed through to your query function as parameters in the order they appear in the array key:

1 function Todos({ completed }) {
2   const queryInfo = useQuery(['todos', { status, page }], fetchTodoList)
3 }
4 
5 // Access the key, status and page variables in your query function!
6 function fetchTodoList(key, { status, page }) {
7   return new Promise()
8   // ...
9 }

If you send through more items in your query key, they will also be available in your query function:

1 function Todo({ todoId, preview }) {
2   const queryInfo = useQuery(['todo', todoId, { preview }], fetchTodoById)
3 }
4 
5 // Access status and page in your query function!
6 function fetchTodoById(key, todoId, { preview }) {
7   return new Promise()
8   // ...
9 }

Whenever a query's key changes, the query will automatically update. In the following example, a new query is created whenever todoId changes:

1 function Todo({ todoId }) {
2   const queryInfo = useQuery(['todo', todoId], fetchTodo)
3 }

Using a Query Object instead of parameters

Anywhere the [queryKey, queryFn, config] signature is supported throughout React Query's API, you can also use an object to express the same configuration:

1 import { useQuery } from 'react-query'
2 
3 useQuery({
4   queryKey: ['todo', 7],
5   queryFn: fetchTodo,
6   config: {},
7 })

Parallel Queries

React Query is built to require no extra effort for making parallel queries. You don't need to do anything special! Just use React Query's hooks and handle all of the loading states and you're good to go!

Dependent Queries

Dependent (or serial) queries are queries that depend on previous ones to finish before they can execute. To do this, use the enabled option to tell a query when it is ready to turn on:

1 // Get the user
2 const { data: user } = useQuery(['user', email], getUserByEmail)
3 
4 // Then get the user's projects
5 const { isIdle, data: projects } = useQuery(
6   ['projects', user?.id],
7   getProjectsByUser,
8   {
9     // `user` would be `null` at first (falsy),
10     // so the query will not execute until the user exists
11     enabled: user,
12   }
13 )
14 
15 // isIdle will be `true` until `enabled` is true and the query begins to fetch.
16 // It will then go to the `isLoading` stage and hopefully the `isSuccess` stage :)

Displaying Background Fetching Loading States

A query's status === 'loading' state is sufficient enough to show the initial hard-loading state for a query, but sometimes you may want to display an additional 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, regardless of the state of the status variable:

1 function Todos() {
2   const { status, data: todos, error, isFetching } = useQuery(
3     'todos',
4     fetchTodos
5   )
6 
7   return status === 'loading' ? (
8     <span>Loading...</span>
9   ) : status === 'error' ? (
10     <span>Error: {error.message}</span>
11   ) : (
12     <>
13       {isFetching ? <div>Refreshing...</div> : null}
14 
15       <div>
16         {todos.map(todo => (
17           <Todo todo={todo} />
18         ))}
19       </div>
20     </>
21   )
22 }

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:

1 import { useIsFetching } from 'react-query'
2 
3 function GlobalLoadingIndicator() {
4   const isFetching = useIsFetching()
5 
6   return isFetching ? (
7     <div>Queries are fetching in the background...</div>
8   ) : null
9 }