Important Defaults

Understanding TanStack Query’s default configurations and when to override them

TanStack Query is configured with aggressive but sensible defaults. Understanding these defaults will help you build better applications and avoid common pitfalls.

Default Query Behavior

By default, TanStack Query assumes you want fresh data and will aggressively refetch to keep your UI synchronized with the server.

Stale Time: 0ms

Queries are immediately considered stale after fetching completes.

// Default behavior - data is immediately stale
const { data } = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  // staleTime: 0 (implicit default)
})

Stale queries are refetched automatically in the background when:

• New instances of the query mount
• The window is refocused
• The network is reconnected
• Configured refetch intervals trigger

Garbage Collection Time: 5 Minutes

Inactive queries are garbage collected after 5 minutes (300,000ms).

// Default gcTime is 5 minutes
const { data } = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  // gcTime: 300000 (implicit default)
})

If users navigate back to a page before gcTime expires, they’ll see cached data instantly. After gcTime expires, there will be a loading state.

Automatic Refetching Defaults

Refetch on Window Focus: true

Queries automatically refetch when the window regains focus if the data is stale.

// This is the default behavior
const { data } = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  refetchOnWindowFocus: true, // default
})

// Disable for specific queries
const { data } = useQuery({
  queryKey: ['static-config'],
  queryFn: fetchConfig,
  refetchOnWindowFocus: false,
})

// Always refetch, even if data is fresh
const { data } = useQuery({
  queryKey: ['real-time-data'],
  queryFn: fetchRealtimeData,
  refetchOnWindowFocus: 'always',
})

Refetch on Mount: true

Queries refetch on mount if the data is stale.

// Default behavior
const { data } = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  refetchOnMount: true, // default
})

// Never refetch on mount
const { data } = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  refetchOnMount: false,
})

Refetch on Reconnect: true

Queries refetch when the network reconnects if the data is stale.

// Default behavior
const { data } = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  refetchOnReconnect: true, // default
})

Retry Defaults

Retry: 3 Attempts

Failed queries retry 3 times with exponential backoff before showing an error.

// Default retry behavior
const { data } = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  retry: 3, // default
})

// Custom retry logic
const { data } = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  retry: (failureCount, error) => {
    // Don't retry on 404
    if (error.status === 404) return false
    // Retry up to 5 times for other errors
    return failureCount < 5
  },
})

Retry Delay: Exponential Backoff

Retries use exponential backoff by default:

// Default retry delay: min(1000 * 2 ** attemptIndex, 30000)
// Attempt 1: ~1 second
// Attempt 2: ~2 seconds  
// Attempt 3: ~4 seconds

// Custom retry delay
const { data } = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  retryDelay: (attemptIndex) => Math.min(1000 * attemptIndex, 5000),
})

Setting Global Defaults

Override defaults globally for all queries:

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60 * 1000, // 1 minute
      gcTime: 5 * 60 * 1000, // 5 minutes (default)
      refetchOnWindowFocus: false,
      refetchOnReconnect: false,
      retry: 1,
    },
    mutations: {
      retry: 1,
    },
  },
})

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
    </QueryClientProvider>
  )
}

Set sensible defaults globally, then override them for specific queries that need different behavior.

Network Mode Defaults

Network Mode: online

Queries and mutations only run when there’s an active network connection.

// Default - only run when online
const { data } = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  networkMode: 'online', // default
})

// Always run, even offline
const { data } = useQuery({
  queryKey: ['offline-data'],
  queryFn: fetchOfflineData,
  networkMode: 'always',
})

// Run when online, but show cached data when offline
const { data } = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  networkMode: 'offlineFirst',
})

Query Enabled Default

Queries are enabled by default and run automatically.

// Default - query runs immediately
const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
  // enabled: true (implicit default)
})

// Conditional execution
const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
  enabled: !!userId, // Only run if userId exists
})

Recommended Configurations

For Static/Slow-Changing Data

const { data } = useQuery({
  queryKey: ['config'],
  queryFn: fetchConfig,
  staleTime: Infinity,
  gcTime: Infinity,
  refetchOnWindowFocus: false,
  refetchOnMount: false,
  refetchOnReconnect: false,
})

For Real-Time Data

const { data } = useQuery({
  queryKey: ['live-data'],
  queryFn: fetchLiveData,
  staleTime: 0,
  refetchInterval: 1000,
  refetchIntervalInBackground: true,
  refetchOnWindowFocus: 'always',
})

For User-Specific Data

const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
  staleTime: 5 * 60 * 1000, // 5 minutes
  gcTime: 10 * 60 * 1000, // 10 minutes
})

For List/Detail Pattern

// List view - shorter stale time
const { data: posts } = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  staleTime: 30 * 1000, // 30 seconds
})

// Detail view - longer stale time, seeded from list
const { data: post } = useQuery({
  queryKey: ['post', postId],
  queryFn: () => fetchPost(postId),
  staleTime: 5 * 60 * 1000, // 5 minutes
  initialData: () => posts?.find(p => p.id === postId),
})

Changing defaults can significantly impact your app’s behavior. Always test thoroughly when adjusting these settings.