swr README

The project's README from github.com/vercel/swr. As one markdown file: README.md.

SWR


Introduction

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:

...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

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>
}

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

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

Contributors

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


License

The MIT License.

swr (vercel/swr)

hooks
Searching Database…

32.5K ·GitHub
Swr
What is this?SWR is a React Hooks library for data fetching. The name comes from stale-while-revalidate (HTTP RFC 5861): cached data is shown first, then the request revalidates and fresh data updates the UI.
Is it a library I install, or a hosted service?A library you install — it's essentially one React hook, useSWR, that you drop into your components. It's fast, lightweight and transport and protocol agnostic, so it works with any backend.
How do I add it to my React project?Install the swr package from npm, then call useSWR with a key (usually your API URL) and a fetcher function. It returns data, isLoading and error, and the full docs are at swr.vercel.app.
Do I need Axios or another data-fetching library for it to work?No — the fetcher can be any asynchronous function, so plain fetch is enough. You can also plug in your favorite data-fetching library if you already have one.
Does my app have to be built with React to use it?Yes — SWR is a React Hooks library, so it's made for React projects, including React Native apps.
Does it work beyond the web browser?Yes — besides web apps it supports React Native for iOS and Android, plus SSR and SSG for server-rendered sites, and it works with React Suspense.
Do I have to pay for it?No — SWR is open source under the MIT license, so it's free to use.
Does the data stay up to date on its own?Yes — components receive a constant stream of updates: SWR revalidates when the window regains focus, when the network recovers, and it also supports polling.
Can it handle writes, or is it read-only?It supports local mutation with optimistic UI — you can update the cached data immediately while the real request settles in the background.
What happens if a request fails?The hook returns an error value alongside data and isLoading, and SWR includes built-in smart error retry, so failed requests are retried automatically.
Is SWR tied to Next.js or Vercel?It's created by the team behind Next.js at Vercel, and with SSR and SSG support it fits Next.js apps nicely — but it's a standalone library for any React project, React Native included.
What are similar projects?query, usehooks, styled-components, react-i18next, nuqs, next.js, ai, astro
Which topics is it in?fetch, hook, ssg, cache, data, vercel, hooks, ssr, react-native, nextjs, react, npm
Creator
vercel
Size
8.1 MB
Stars
32.5K
Updated
CommitOct 16Releasev2.5.1Aug 12
Age
6y
Commits · 90 Days