Skip to content
Docs
API

API

const { data, error, isLoading, isValidating, mutate } = useSWR(key, fetcher, options)

Parameters

  • key: a unique key string for the request (or a function / array / null) (details), (advanced usage)
  • fetcher: (optional) a Promise-returning function to fetch your data (details)
  • options: (optional) an object of options for this SWR hook

Return Values

  • data: data for the given key resolved by fetcher (or undefined if not loaded)
  • error: error thrown by fetcher (or undefined)
  • isLoading: if there's an ongoing request and no "loaded data". Fallback data and previous data are not considered "loaded data"
  • isValidating: if there's a request or revalidation loading
  • mutate(data?, options?): function to mutate the cached data (details)

More information can be found here.

Options

  • suspense = false: enable React Suspense mode (details)
  • fetcher(args): the fetcher function
  • revalidateIfStale = true: automatically revalidate even if there is stale data (details)
  • revalidateOnMount: enable or disable automatic revalidation when component is mounted (details)
  • revalidateOnFocus = true: automatically revalidate when window gets focused (details)
  • revalidateOnReconnect = true: automatically revalidate when the browser regains a network connection (via navigator.onLine) (details)
  • refreshInterval (details):
    • Disabled by default: refreshInterval = 0
    • If set to a number, polling interval in milliseconds
    • If set to a function, the function will receive the latest data and should return the interval in milliseconds
  • refreshWhenHidden = false: polling when the window is invisible (if refreshInterval is enabled)
  • refreshWhenOffline = false: polling when the browser is offline (determined by navigator.onLine)
  • shouldRetryOnError = true: retry when fetcher has an error
  • dedupingInterval = 2000: dedupe requests with the same key in this time span in milliseconds
  • focusThrottleInterval = 5000: only revalidate once during a time span in milliseconds
  • loadingTimeout = 3000: timeout to trigger the onLoadingSlow event in milliseconds
  • errorRetryInterval = 5000: error retry interval in milliseconds
  • errorRetryCount: max error retry count
  • fallback: a key-value object of multiple fallback data (example)
  • fallbackData: initial data to be returned (note: This is per-hook)
  • keepPreviousData = false: return the previous key's data until the new data has been loaded (details)
  • onLoadingSlow(key, config): callback function when a request takes too long to load (see loadingTimeout)
  • onSuccess(data, key, config): callback function when a request finishes successfully
  • onError(err, key, config): callback function when a request returns an error
  • onErrorRetry(err, key, config, revalidate, revalidateOps): handler for error retry
  • onDiscarded(key): callback function when a request is ignored due to race conditions
  • compare(a, b): comparison function used to detect when returned data has changed, to avoid spurious rerenders. By default, stable-hash (opens in a new tab) is used.
  • isPaused(): function to detect whether pause revalidations, will ignore fetched data and errors when it returns true. Returns false by default.
  • use: array of middleware functions (details)
💡

When under a slow network (2G, <= 70Kbps), errorRetryInterval will be 10s, and loadingTimeout will be 5s by default.

You can also use global configuration to provide default options.