Dependent or conditional fetching
A query needs an identifier, token, or form input before its first request.
TanStack · Pipe
enabled
The enabled option controls whether a query runs automatically. Set it to false to defer fetching, then use refetch for manual execution when needed.
How it works
Set enabled to false, or to a callback-like condition through derived state, when a query must wait before automatically fetching. Disabled queries can still be triggered with refetch, while enabled queries participate in normal mounting, background-refetching, and invalidation behavior.
Syntax
useQuery({ queryKey, queryFn, enabled: boolean })Parameters
| Name | Type | Description |
|---|---|---|
enabled | boolean | () => boolean | Boolean or a function returning a boolean that controls whether the query is enabled. |
Returns
No standalone return value; useQuery exposes refetch for manual triggering.
Key points
- Use enabled: false to stop a query from automatically running.
- The enabled condition may be computed dynamically rather than fixed permanently.
- A disabled query does not start a request when its component mounts.
- Background refetching is paused while enabled resolves to false.
- Use the hook's refetch function for an explicit request when automatic execution is disabled.
- Changing the enabling condition supports lazy queries that begin after required input is ready.
Common mistakes
- Do not expect refetch returned by the query hook to work when the query is disabled with skipToken.
- A disabled query does not respond to invalidation or refetch calls that would ordinarily cause it to fetch.
Example: Conditionally enable a query
import { useQuery } from '@tanstack/react-query'
export function Todos({ userId }: { userId?: string }) {
const query = useQuery({
queryKey: ['todos', userId],
queryFn: () => fetch(`/api/todos?userId=${userId}`).then(r => r.json()),
enabled: Boolean(userId),
})
return <pre>{JSON.stringify(query.data ?? [], null, 2)}</pre>
}The query waits until userId exists, then runs normally.
When to use it
Lazy/manual queries
A screen should wait for an explicit user action before requesting data.
State-gated data loading
A request should remain inactive until application state satisfies a condition.
Interview questions
QWhat does enabled: false do?
Set enabled to false to prevent automatic execution. The hook can still expose cached data, and refetch can manually trigger the request.
Follow-up: How does disabled state differ with cached data? With cached data the query starts successful; without it, it starts pending with an idle fetch status.
QWhich automatic behaviors are suppressed?
A disabled query does not fetch on mount, does not background-refetch, and ignores relevant invalidateQueries and refetchQueries calls. This makes it useful when fetching should be controlled explicitly.
Follow-up: How can a query become lazy rather than permanently disabled? Change the condition used for enabled when the required input becomes available.
QWhen should enabled be preferred over skipToken?
The documentation recommends enabled: false when manual refetching is needed, because refetch works properly there. skipToken is a typesafe alternative for disabling a TypeScript query, but it does not support that refetch behavior.
Follow-up: When is skipToken preferable? Use it when conditional disabling should preserve type safety and manual refetch is not required.
Related
skipTokenuseQueryrefetchinvalidateQueriesrefetchQueriesDependent Queries