Open History to see the last commit
1---
2id: disabling-queries
3title: Disabling/Pausing Queries
4---
5β
6If you ever want to disable a query from automatically running, you can use the `enabled = false` option. The enabled option also accepts a callback that returns a boolean.
7β
8When `enabled` is `false`:
9β
10- If the query has cached data, then the query will be initialized in the `status === 'success'` or `isSuccess` state.
11- If the query does not have cached data, then the query will start in the `status === 'pending'` and `fetchStatus === 'idle'` state.
12- The query will not automatically fetch on mount.
13- The query will not automatically refetch in the background.
14- The query will ignore query client `invalidateQueries` and `refetchQueries` calls that would normally result in the query refetching.
15- `refetch` returned from `useQuery` can be used to manually trigger the query to fetch. However, it will not work with `skipToken`.
16β
17> TypeScript users may prefer to use [skipToken](#typesafe-disabling-of-queries-using-skiptoken) as an alternative to `enabled = false`.
18β
19[//]: # 'Example'
20β
21```tsx
22function Todos() {
23 const { isLoading, isError, data, error, refetch, isFetching } = useQuery({
24 queryKey: ['todos'],
25 queryFn: fetchTodoList,
26 enabled: false,
27 })
28β
29 return (
30 <div>
31 <button onClick={() => refetch()}>Fetch Todos</button>
32β
33 {data ? (
34 <ul>
35 {data.map((todo) => (
36 <li key={todo.id}>{todo.title}</li>
37 ))}
38 </ul>
39 ) : isError ? (
40 <span>Error: {error.message}</span>
41 ) : isLoading ? (
42 <span>Loading...</span>
43 ) : (
44 <span>Not ready ...</span>
45 )}
46β
47 <div>{isFetching ? 'Fetching...' : null}</div>
48 </div>
49 )
50}
51```
52β
53[//]: # 'Example'
54β
55Permanently disabling a query opts out of many great features that TanStack Query has to offer (like background refetches), and it's also not the idiomatic way. It takes you from the declarative approach (defining dependencies when your query should run) into an imperative mode (fetch whenever I click here). It is also not possible to pass parameters to `refetch`. Oftentimes, all you want is a lazy query that defers the initial fetch:
56β
57## Lazy Queries
58β
59The enabled option can not only be used to permanently disable a query, but also to enable / disable it at a later time. A good example would be a filter form where you only want to fire off the first request once the user has entered a filter value:
60β
61[//]: # 'Example2'
62β
63```tsx
64function Todos() {
65 const [filter, setFilter] = React.useState('')
66β
67 const { data } = useQuery({
68 queryKey: ['todos', filter],
69 queryFn: () => fetchTodos(filter),
70 // β¬οΈ disabled as long as the filter is empty
71 enabled: !!filter,
72 })
73β
74 return (
75 <div>
76 // π applying the filter will enable and execute the query
77 <FiltersForm onApply={setFilter} />
78 {data && <TodosTable data={data} />}
79 </div>
80 )
81}
82```
83β
84[//]: # 'Example2'
85β
86### isLoading (Previously: `isInitialLoading`)
87β
88Lazy queries will be in `status: 'pending'` right from the start because `pending` means that there is no data yet. This is technically true, however, since we are not currently fetching any data (as the query is not _enabled_), it also means you likely cannot use this flag to show a loading spinner.
89β
90If you are using disabled or lazy queries, you can use the `isLoading` flag instead. It's a derived flag that is computed from:
91β
92`isPending && isFetching`
93β
94so it will only be true if the query is currently fetching for the first time.
95β
96## Typesafe disabling of queries using `skipToken`
97β
98If you are using TypeScript, you can use the `skipToken` to disable a query. This is useful when you want to disable a query based on a condition, but you still want the query to be type safe.
99β
100> **IMPORTANT**: `refetch` from `useQuery` will not work with `skipToken`. Calling `refetch()` on a query that uses `skipToken` will result in a `Missing queryFn` error because there is no valid query function to execute. If you need to manually trigger queries, consider using `enabled: false` instead, which allows `refetch()` to work properly. Other than this limitation, `skipToken` works the same as `enabled: false`.
101β
102[//]: # 'Example3'
103β
104```tsx
105import { skipToken, useQuery } from '@tanstack/react-query'
106β
107function Todos() {
108 const [filter, setFilter] = React.useState<string | undefined>()
109β
110 const { data } = useQuery({
111 queryKey: ['todos', filter],
112 // β¬οΈ disabled as long as the filter is undefined or empty
113 queryFn: filter ? () => fetchTodos(filter) : skipToken,
114 })
115β
116 return (
117 <div>
118 // π applying the filter will enable and execute the query
119 <FiltersForm onApply={setFilter} />
120 {data && <TodosTable data={data} />}
121 </div>
122 )
123}
124```
125β
126[//]: # 'Example3'