Queries

Query Basics

A query is a declarative dependency on an asynchronous source of data that is tied to a unique key. 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 subscribe to a query in your components or custom hooks, call the useQuery hook with at least:

• A unique key for the query
• A function that returns a promise that:
  • Resolves the data, or
  • Throws an error

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, and sharing your queries throughout your application.

The query results returned by useQuery contains all of the information about the query that you'll need for templating and any other usage of the data:

 const result = useQuery('todos', fetchTodoList)

The result object contains a few very important states you'll need to be aware of to be productive. A query can only be in one of the following states at any given moment:

• isLoading or status === 'loading' - The query has no data and is currently fetching
• isError or status === 'error' - The query encountered an error
• isSuccess or status === 'success' - The query was successful and data is available
• isIdle or status === 'idle' - The query is currently disabled (you'll learn more about this in a bit)

Beyond those primary states, more information is available depending on the state of the query:

• error - If the query is in an isError state, the error is available via the error property.
• data - If the query is in a success state, the data is available via the data property.
• isFetching - In any state, if the query is fetching at any time (including background refetching) isFetching will be true.

For most queries, it's usually sufficient to check for the isLoading state, then the isError state, then finally, assume that the data is available and render the successful state:

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   // We can assume by this point that `isSuccess === true`
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 always use the status state as well:

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 }

Further Reading

For an alternative way of performing status checks, have a look at the Community Resources.