Polling in React with TanStack Query and refetchInterval

Some data changes without the user doing anything. A build that is still running, an order working its way through fulfilment, a sensor reporting every few minutes. The screen has to keep up, and the simplest way to do that is to ask again on a timer.

TanStack Query makes this one option on a hook you are probably already using: refetchInterval. What follows is how to set it, the defaults that will surprise you, and the two mistakes that turn polling into a support ticket. The full option list is in the useQuery reference if you want it alongside.

Why Choose TanStack Query and refetchInterval for Polling?

Polling is how most dashboards read data that a device pushes on its own schedule. If the device end is what you are building, the ESP32 weather station covers publishing readings over MQTT from the hardware side. And if you are weighing polling against a push transport at all, the trade-offs are laid out in WebSockets vs SSE vs polling.

TanStack Query handles server state, meaning data that lives on a backend and needs syncing. If you are weighing it against a plain effect or SWR, start with fetching data in React. Server state is a different problem from the client state covered in React state management. Before we jump into the implementation, let's understand why it is an excellent choice for polling in React applications:

• Simplicity: TanStack Query abstracts away many of the complexities involved in data fetching, caching, and synchronization.
• Flexibility: It offers a range of options to customize polling behavior, from simple intervals to dynamic adjustments based on data freshness.
• Performance: With built-in caching and deduplication, TanStack Query ensures efficient network usage and optimal performance.

Now, let's get started with setting up your React environment for polling with TanStack Query.

Setting Up Your React Environment with TanStack Query

First things first, you'll need to install TanStack Query in your React project. You can do this using npm or yarn:

npm install @tanstack/react-query
# or
yarn add @tanstack/react-query

Once installed, wrap your application with the QueryClientProvider from TanStack Query. This provider makes the query client available throughout your app, allowing components to fetch and manage data seamlessly.

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

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* Your app components */}
    </QueryClientProvider>
  );
}

export default App;

With the setup complete, we're ready to implement polling in our React components.

Implementing Basic Polling with TanStack Query

TanStack Query's useQuery hook is your go-to tool for fetching data, and it supports polling right out of the box. To enable polling, simply set the refetchInterval option to specify the interval (in milliseconds) at which the data should be refetched.

Here's a basic example of polling an API endpoint every 5 seconds:

import { useQuery } from '@tanstack/react-query';
import axios from 'axios';

const fetchData = async () => {
  const response = await axios.get('https://api.example.com/data');
  return response.data;
};

const PollingComponent = () => {
  const { data, isLoading, error } = useQuery({
    queryKey: ['data'],
    queryFn: fetchData,
    refetchInterval: 5000, // Poll every 5 seconds
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h1>Polling Data</h1>
      <pre>{JSON.stringify(data, null, 2)}</pre>
    </div>
  );
};

export default PollingComponent;

In this example, the PollingComponent fetches data from the specified API endpoint every 5 seconds, displaying the data or loading/error states as appropriate.

Advanced Polling Techniques

While basic polling is straightforward, TanStack Query offers several advanced options to fine-tune your polling behavior.

How do you poll conditionally?

You can control polling based on user activity or other conditions using the refetchOnWindowFocus option. This ensures that data is only fetched when the user is actively interacting with your app, reducing unnecessary network requests.

const { data, isLoading, error } = useQuery({
  queryKey: ['data'],
  queryFn: fetchData,
  refetchInterval: 5000,
  refetchOnWindowFocus: true, // Refetch when window regains focus
});

Can the polling interval change at runtime?

For scenarios where the polling interval should adjust based on data freshness or other factors, you can use a function for refetchInterval. This function receives the current data as an argument, allowing you to make informed decisions about when to refetch.

const { data, isLoading, error } = useQuery({
  queryKey: ['data'],
  queryFn: fetchData,
  refetchInterval: (data) => data?.needsRefresh ? 5000 : false, // Poll only if data needs refresh
});

In this example, polling occurs every 5 seconds only if the data indicates a need for refresh. Otherwise, polling is paused.

Stop polling when the tab is hidden

This is the single most valuable addition to any polling setup, and it is one option. A background tab polling every five seconds burns the user's battery and your server capacity to update a screen nobody is looking at. TanStack Query pauses refetching for backgrounded tabs by default, but only if you leave refetchIntervalInBackground at its default of false.

const { data } = useQuery({
  queryKey: ['prices'],
  queryFn: fetchPrices,
  refetchInterval: 5000,
  // Default. Setting this to true is almost always a mistake:
  // every backgrounded tab keeps hitting your API forever.
  refetchIntervalInBackground: false,
});

The exception is something the user genuinely needs updated while they are elsewhere, such as a build that should fire a notification on completion. Even then, consider whether the server should push instead.

Back off when requests fail

A fixed interval against a failing endpoint is a retry storm. If the API is down, every client hammers it every five seconds, which is exactly the load pattern that keeps it down. Because refetchInterval accepts a function, the interval can respond to failures:

const query = useQuery({
  queryKey: ['status', jobId],
  queryFn: () => fetchStatus(jobId),
  refetchInterval: (q) => {
    // Back off exponentially while the endpoint is failing.
    if (q.state.status === 'error') {
      return Math.min(60_000, 2 ** q.state.fetchFailureCount * 1000);
    }
    // Stop entirely once the job is finished.
    return q.state.data?.done ? false : 3000;
  },
});

Returning false is how polling stops. Forgetting that is the most common bug in this pattern: a job-status poller that keeps querying a completed job for as long as the component stays mounted, which on a dashboard can be hours.

Match the interval to how fast the data actually changes

The instinct is to poll fast so the UI feels live. The cost is linear in clients: at one second, a thousand concurrent users generate a thousand requests per second, and almost all of them return data identical to the last response.

Below roughly a second, polling stops being the right tool. The comparison with WebSockets and Server-Sent Events, including why SSE is usually the better upgrade, is in WebSockets vs SSE vs polling.

Set staleTime, or the interval is not the only fetch

A frequent surprise: the data refetches more often than the interval suggests. That is because refetchInterval is not the only trigger. Window focus, network reconnect and component remounts all refetch by default when data is stale, and the default staleTime is zero, meaning always stale.

useQuery({
  queryKey: ['metrics'],
  queryFn: fetchMetrics,
  refetchInterval: 30_000,
  // Treat data as fresh for most of the interval, so tab focus and
  // remounts do not add a second stream of requests on top.
  staleTime: 25_000,
});

Without this, tabbing away and back fires an immediate extra request every time, which on a dashboard people switch between constantly can double or triple the real request volume.

Best Practices for Polling with TanStack Query

To ensure your polling implementation is efficient and user-friendly, consider the following best practices:

• Error Handling: Always handle errors gracefully by displaying user-friendly messages or fallback content.
• Optimize Network Usage: Adjust polling intervals based on the criticality of data freshness. For less critical data, consider longer intervals to reduce network load.
• Leverage DevTools: Use TanStack Query DevTools to monitor and debug your queries, ensuring everything is working as expected.

Conclusion

Polling is a powerful technique for fetching real-time data in React applications, and TanStack Query makes it easier than ever to implement. With its simple setup, flexible options, and robust performance optimizations, TanStack Query is an excellent choice for developers looking to add real-time data fetching to their React apps.

By following the guidelines and examples provided in this article, you're well-equipped to start implementing polling in your React projects today. Happy coding!

Further Reading

• TanStack Query Official Documentation
• React Documentation

By incorporating these resources and continuing to explore TanStack Query's features, you'll be able to take your React applications to the next level with efficient, real-time data fetching.