swr Documentation

File: README.md Copy Chapter

Introduction Copy Chapter

SWR is a React Hooks library for data fetching.

The name “SWR” is derived from stale-while-revalidate, a cache invalidation strategy popularized by HTTP RFC 5861.
SWR first returns the data from cache (stale), then sends the request (revalidate), and finally comes with the up-to-date data again.

With just one hook, you can significantly simplify the data fetching logic in your project. And it also covered in all aspects of speed, correctness, and stability to help you build better experiences:

• Fast, lightweight and reusable data fetching
• Transport and protocol agnostic
• Built-in cache and request deduplication
• Real-time experience
• Revalidation on focus
• Revalidation on network recovery
• Polling
• Pagination and scroll position recovery
• SSR and SSG
• Local mutation (Optimistic UI)
• Built-in smart error retry
• TypeScript
• React Suspense
• React Native

...and a lot more.

With SWR, components will get a stream of data updates constantly and automatically. Thus, the UI will be always fast and reactive.

View full documentation and examples on swr.vercel.app.

Quick Start Copy Chapter

import useSWR from 'swr'

function Profile() {
  const { data, error, isLoading } = useSWR('/api/user', fetcher)

  if (error) return failed to load
  if (isLoading) return loading...
  return hello {data.name}!
}

In this example, the React Hook useSWR accepts a key and a fetcher function.
The key is a unique identifier of the request, normally the URL of the API. And the fetcher accepts
key as its parameter and returns the data asynchronously.

useSWR also returns 3 values: data, isLoading and error. When the request (fetcher) is not yet finished,
data will be undefined and isLoading will be true. When we get a response, it sets data and error based on the result
of fetcher, isLoading to false and rerenders the component.

Note that fetcher can be any asynchronous function, you can use your favourite data-fetching
library to handle that part.

View full documentation and examples on swr.vercel.app.

Authors Copy Chapter

This library is created by the team behind Next.js, with contributions from our community:

• Shu Ding (@shuding_) - Vercel
• Jiachi Liu (@huozhi) - Vercel
• Guillermo Rauch (@rauchg) - Vercel
• Joe Haddad (@timer150) - Vercel
• Paco Coursey (@pacocoursey) - Vercel

Contributors

Thanks to Ryan Chen for providing the awesome swr npm package name!

License Copy Chapter

The MIT License.

File: examples/api-hooks/README.md Copy Chapter

API Hooks

One-Click Deploy Copy Chapter

Deploy your own SWR project with Vercel.

How to Use Copy Chapter

Download the example:

curl https://codeload.github.com/vercel/swr/tar.gz/main | tar -xz --strip=2 swr-main/examples/api-hooks
cd api-hooks

Install it and run:

yarn
yarn dev
# or
npm install
npm run dev

The Idea behind the Example Copy Chapter

Show how you could create custom hooks, using SWR internally, for your different data requirements and use them in your application.

File: examples/autocomplete-suggestions/README.md Copy Chapter

Autocomplete Suggestions

One-Click Deploy Copy Chapter

Deploy your own SWR project with Vercel.

How to Use Copy Chapter

Download the example:

curl https://codeload.github.com/vercel/swr/tar.gz/main | tar -xz --strip=2 swr-main/examples/autocomplete-suggestions
cd autocomplete-suggestions

Install it and run:

yarn
yarn dev
# or
npm install
npm run dev

The Idea behind the Example Copy Chapter

Show how to use SWR to fetch the suggestion for an autocomplete.

File: examples/basic/README.md Copy Chapter

Basic

One-Click Deploy Copy Chapter

Deploy your own SWR project with Vercel.

How to Use Copy Chapter

Download the example:

curl https://codeload.github.com/vercel/swr/tar.gz/main | tar -xz --strip=2 swr-main/examples/basic
cd basic

Install it and run:

yarn
yarn dev
# or
npm install
npm run dev

The Idea behind the Example Copy Chapter

Show a basic usage of SWR fetching data from an API in two different pages.

File: examples/basic-typescript/README.md Copy Chapter

Basic TypeScript

One-Click Deploy Copy Chapter

Deploy your own SWR project with Vercel.

How to Use Copy Chapter

Download the example:

curl https://codeload.github.com/vercel/swr/tar.gz/main | tar -xz --strip=2 swr-main/examples/basic-typescript
cd basic-typescript

Install it and run:

yarn
yarn dev
# or
npm install
npm run dev

The Idea behind the Example Copy Chapter

Show how to use the basic example along with TypeScript to type the data received from SWR.

File: examples/focus-revalidate/README.md Copy Chapter

Focus Revalidate

One-Click Deploy Copy Chapter

Deploy your own SWR project with Vercel.

How to Use Copy Chapter

Download the example:

curl https://codeload.github.com/vercel/swr/tar.gz/main | tar -xz --strip=2 swr-main/examples/focus-revalidate
cd focus-revalidate

Install it and run:

yarn
yarn dev
# or
npm install
npm run dev

The Idea behind the Example Copy Chapter

Basic authentication example showing how the revalidate on focus feature works and to trigger a revalidation on a per-hook call basis.

File: examples/global-fetcher/README.md Copy Chapter

Global Fetcher

One-Click Deploy Copy Chapter

Deploy your own SWR project with Vercel.

How to Use Copy Chapter

Download the example:

curl https://codeload.github.com/vercel/swr/tar.gz/main | tar -xz --strip=2 swr-main/examples/global-fetcher
cd global-fetcher

Install it and run:

yarn
yarn dev
# or
npm install
npm run dev

The Idea behind the Example Copy Chapter

Use the SWRConfig provider to set up the fetcher globally instead of a per-hook call.