---
title: API
docs_index: /llms.txt
lastUpdated: 2026-02-12
type: reference
summary: Complete API reference for SWR hooks and utilities.
prerequisites:
  - /docs/getting-started
related:
  - /docs/global-configuration
  - /docs/typescript
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

```js
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)](/docs/arguments), [(advanced usage)](/docs/conditional-fetching)
- `fetcher`: (*optional*) a Promise-returning function to fetch your data [(details)](/docs/data-fetching)
- `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)](/docs/mutation)

More information can be found [here](/docs/advanced/understanding).

## Options

- `suspense = false`: enable React Suspense mode [(details)](/docs/suspense)
- `fetcher(args)`: the fetcher function
- `revalidateIfStale = true`: automatically revalidate even if there is stale data [(details)](/docs/revalidation#disable-automatic-revalidations)
- `revalidateOnMount`: enable or disable automatic revalidation when component is mounted [(details)](/docs/revalidation#revalidate-on-mount)
- `revalidateOnFocus = true`: automatically revalidate when window gets focused [(details)](/docs/revalidation)
- `revalidateOnReconnect = true`: automatically revalidate when the browser regains a network connection (via `navigator.onLine`) [(details)](/docs/revalidation)
- `refreshInterval` [(details)](/docs/revalidation):
  - 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)](/docs/with-nextjs)
- `fallbackData`: initial data to be returned (note: This is per-hook)
- `strictServerPrefetchWarning = false`: show a warning message in the console when a key has no pre-filled data provided [(details)](/docs/with-nextjs#prefetch-data-in-server-components)
- `keepPreviousData = false`: return the previous key's data until the new data has been loaded [(details)](/docs/advanced/understanding#return-previous-data-for-better-ux)
- `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](https://github.com/shuding/stable-hash) 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)](/docs/middleware)

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

You can also use [global configuration](/docs/global-configuration) to provide default options.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)