Query Functions

A query function can be literally any function that returns a promise. The promise that is returned should either resolve the data or throw an error.

All of the following are valid query function configurations:

1 useQuery(['todos', todoId], fetchTodoById)
2 useQuery(['todos', todoId], () => fetchTodoById(todoId))
3 useQuery(['todos', todoId], async () => {
4   const data = await fetchTodoById(todoId)
5   return data
6 })

Handling and Throwing Errors

For React Query to determine a query has errored, the query function must throw. Any error that is thrown in the query function will be persisted on the error state of the query.

1 const { error } = useQuery(['todos', todoId], async () => {
2   if (somethingGoesWrong) {
3     throw new Error('Oh no!')
4   }
5 
6   return data
7 })

Usage with fetch and others clients that do not throw by default

While most utilities like axios or graphql-request automatically throw errors for unsuccessful HTTP calls, some utilities like fetch do not throw errors by default. If that's the case, you'll need to throw them on your own. Here is a simple way to do that with the popular fetch API:

1 useQuery(['todos', todoId], async () => {
2   const { ok, json } = await fetch('/todos/' + todoId)
3   if (!ok) {
4     throw new Error('Network response was not ok')
5   }
6   return json()
7 })

Query Function Variables

Query keys are not just for uniquely identifying the data you are fetching, but are also conveniently passed as variables for your query function and while not always necessary, this makes it possible to extract your query functions if needed. The individual parts of the query key get passed through to your query function as parameters in the same order they appear in the array key:

1 function Todos({ completed }) {
2   const result = 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 result = 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 }

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 })