import { Callout } from 'nextra/components'

API Options

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

Parameters

• key: a unique key string for the request (or a function / array / null) (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)
• isValidating: if there's a request or revalidation loading
• mutate(data?, shouldRevalidate?): function to mutate the cached data (details)

Options

• suspense = false: enable React Suspense mode (details)
• fetcher(args): the fetcher function
• revalidateIfStale = true: automatic revalidation on mount even if there is stale data (details)
• revalidateOnMount: enable or disable automatic revalidation when component is mounted
• 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)
• 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
• compare(a, b): comparison function used to detect when returned data has changed, to avoid spurious rerenders. By default, dequal 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)

You can also use global configuration to provide default options.