Guide · Open source
How to use SWR: install, fetch data and cache in React
Updated · written with AI from the project's own documentation and checked against our catalogue data
SWR is a React Hooks library for loading data in web interfaces. It shows cached data first, requests fresh data in the background, and updates the screen when the new data arrives. This guide shows you how to install it, call the useSWR hook, and understand the values it returns, so you can load data in a React component.
SWRvercel/swr · ★ 32.5k · MIT Install options & downloads Quick start
- 1Install the package. Run npm install swr in a project that has Node.js and React.
- 2Import the hook. Import useSWR from 'swr' in the component that needs data.
- 3Write a fetcher. Create an asynchronous function that takes the key and returns the data.
- 4Call useSWR with a key. Pass a unique key, such as an API URL, and your fetcher to useSWR.
- 5Render each state. Use error, isLoading and data to show a failure message, a loading message or the result.
What does SWR do?
The name SWR comes 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 returns the up-to-date data.
The library is meant to simplify the data fetching logic in your project with a single hook.
- Built-in cache and request deduplication
- Revalidation on focus and on network recovery
- Polling
- Built-in smart error retry
- TypeScript support and React Native support
Install SWR with npm
SWR is installed as a package. You need Node.js and a package manager such as npm, plus React in your project.
npm install swrFetch data with the useSWR hook
The useSWR hook accepts a key and a fetcher function. The key is a unique identifier of the request, normally the URL of the API. The fetcher accepts the key as its parameter and returns the data asynchronously.
The hook returns data, isLoading and error. While the request is not finished, data is undefined and isLoading is true. When the response arrives, SWR sets data or error based on the result of the fetcher, sets isLoading to false, and re-renders the component.
The fetcher can be any asynchronous function, so you can use your favourite data-fetching library for that part.
import useSWR from 'swr'
function Profile() {
const { data, error, isLoading } = useSWR('/api/user', fetcher)
if (error) return <div>failed to load</div>
if (isLoading) return <div>loading...</div>
return <div>hello {data.name}!</div>
}Handle loading and error states
Check error first, then isLoading, before rendering data. This order means your component never reads data while the request is still running or after it has failed.
- error: set when the fetcher fails
- isLoading: true until the first request finishes
- data: undefined until a response arrives
Use SWR features like revalidation and polling
The README lists revalidation on focus, revalidation on network recovery and polling among SWR's features. Its documentation at swr.vercel.app covers how to configure these options and the other features listed, such as pagination, SSR and SSG, and optimistic local mutation.
- Revalidation on focus
- Revalidation on network recovery
- Polling
- Pagination and scroll position recovery
- Local mutation (Optimistic UI)
What people use it for
- Loading a user profile from an API inside a React component
- Keeping a dashboard's data fresh with polling or revalidation on focus
- Building React Native or Next.js interfaces that fetch data from APIs
- Showing cached data immediately while fresh data loads in the background
Frequently asked questions
Is SWR free to use?
SWR is released under the MIT License, as stated in the README. The license permits use, and the repository's LICENSE file has the full terms.
What do I need before installing SWR?
The README lists Node.js and a package manager such as npm, plus React. You install the package with npm install swr.
What is the difference between SWR and TanStack Query?
Both are data-fetching libraries for React. This page does not compare them in detail, so check each project's documentation for feature differences. Other comparable projects named for this item include RTK Query and Apollo Client.
What does the key in useSWR do?
The key is a unique identifier of the request, normally the URL of the API. SWR uses it to identify the cached data and the request.
Can I use SWR with any data-fetching method?
Yes. The README says the fetcher can be any asynchronous function, so you can use your favourite data-fetching library for that part.
Is SWR only for beginners or for experienced developers?
SWR is built around React Hooks, so you need to know JavaScript and React first. People with no React experience would need to learn those before using it.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
SWR suits React developers who fetch data from APIs in components and want built-in caching, request deduplication and automatic refresh. If you do not write React, or you need a full server-side data layer rather than client-side fetching hooks, pick a different tool.
Install options & downloads