poll

Description: Re-executes the data-fetching action at a specified interval (in milliseconds).

Default Value: 0 (Polling disabled).

Polling is useful for data that updates frequently, such as live statistics, notifications, or dashboard data.

• How To: Use poll for real-time data. Combine it with suspendAfterFirstLoad: false for a smooth user experience that avoids UI flickering on subsequent polls.

  // Correct: Poll for live stats every 5 seconds without re-suspending
  useFetch(
      'live-stats',
      fetchLiveStats,
      {
          suspense: true,
          suspendAfterFirstLoad: false,
          poll: 5000, // Re-fetch every 5 seconds
          ttl: 0, // Ensure data is always considered stale for re-fetch
      }
  );

---

How Polling Interacts with ttl

For a poll to trigger a new data fetch, the existing data in the cache must be considered "stale". The ttl (time-to-live) option determines how long cached data is considered fresh.

• Rule: The execute function, which is called by the poll, will only proceed if it determines a fetch is necessary—typically by checking if the data is stale.
• Best Practice: When using poll, set ttl: 0. This makes the data instantly stale, ensuring that every poll interval triggers a new network request. If ttl is longer than the poll interval, the poll will fire, but it won't re-fetch data until the ttl expires.

---

How to Stop Polling

Polling automatically stops when the component using the useFetch hook is unmounted. However, you might want to stop it dynamically while the component remains mounted.

⚠️ Known Limitation / Bug Currently, dynamically changing the poll option to 0 on an actively running useFetch hook will not stop the existing polling interval. This is due to a missing internal dependency in the hook's effect that fails to react to the change.

Workaround: Setting enabled to false

To reliably stop an active poll, you must disable the useFetch hook entirely. Setting enabled: false correctly cleans up the polling interval and prevents any other form of automatic data fetching for that hook.

import { useState } from 'react';

function MyComponent() {
    const [isPollingActive, setIsPollingActive] = useState(true);

    useFetch(
        'some-key',
        fetchData,
        {
            enabled: isPollingActive, // Setting this to false stops the poll
            poll: 5000,
            ttl: 0,
        }
    );

    return (
        <button onClick={() => setIsPollingActive(false)}>
            Stop Polling (Disable Hook)
        </button>
    );
}

---

Best Practices Summary

• Avoid Re-suspense: Always use suspendAfterFirstLoad: false with poll to prevent the UI from showing a loading fallback on every interval.
• Ensure Re-fetching: Set ttl: 0 to make sure each poll interval results in a new data fetch.
• Stop Dynamically: To reliably stop a poll, re-render your component with enabled: false.
• Be Mindful of Resources: Avoid polling too frequently for non-critical data to reduce server load and network traffic.

// Avoid this: Causes loading fallback to flash every 5 seconds
useFetch(
    'frequently-updated-data',
    () => fetchFrequentData(),
    {
        suspense: true,
        suspendAfterFirstLoad: true, // This is the anti-pattern
        poll: 5000
    }
);