NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #2622 most downloaded on npm
React Hooks library for remote data fetching
Last release 12 days ago
22 Sep 2026
Release timing varies
gaps range from 9 days to 4 months
Nearly every release is documented
notes for 57 of the last 60 stable releases
1 version withdrawn
withdrawn after publishing
8 years old
181 releases · first in 2018
Add cache tag revalidation support by @WITS in #4336
One column per quarter.
chore: remove deprecated eslint config files by @abhiramvsmg in #4308
Full Changelog: v2.5.0...v2.5.1
Preload data in React Server Components and pass it to client hooks through SWRConfig. This avoids a duplicate initial browser request and hydrates th
Preload data in React Server Components and pass it to client hooks through SWRConfig. This avoids a duplicate initial browser request and hydrates the result into the SWR cache. The new cacheData option is experimental.
https://github.com/vercel/swr/pull/4275
unload() APIUse unload() to clear the entire SWR cache and discard in-flight requests and mutations. Mounted hooks revalidate by default, or you can pass { revalidate: false } to keep the cache empty until the next revalidation.
https://github.com/vercel/swr/pull/4298
swr/_internal React Server export so it resolves correctly in the published package by @pengshenghai in https://github.com/vercel/swr/pull/4272Full Changelog: https://github.com/vercel/swr/compare/v2.4.2...v2.5.0
Preload data in React Server Components and pass it to client hooks through SWRConfig. This avoids a duplicate initial browser request and hydrates the result into the SWR cache. The new cacheData option is experimental.
unload() APIUse unload() to clear the entire SWR cache and discard in-flight requests and mutations. Mounted hooks revalidate by default, or you can pass { revalidate: false } to keep the cache empty until the next revalidation.
swr/_internal React Server export so it resolves correctly in the published package by @pengshenghai in #4272Full Changelog: v2.4.2...v2.5.0
feat: unload() api by @huozhi in #4298
feat: rsc fetches and prefill swr cache by @huozhi in #4275
Full Changelog: v2.4.2...v2.5.0-beta.0
fix: guard against double-unsubscribe removing wrong subscriber in cache.ts by @tomohiro86 in #4252
Full Changelog: v2.4.1...v2.4.2
Remove deprecated downlevelIteration option by @RyanCavanaugh in #4216
Full Changelog: v2.4.0...v2.4.1
chore: Migrate suspense related tests to e2e by @promer94 in #4204
Full Changelog: v2.3.8...v2.4.0
fix: cve-2025-55182 critical rce vulnerability by @PierreCrb in #4192
act from React by @shuding in #4202Full Changelog: v2.3.7...v2.3.8
deps: upgrade ci node version to 22 by @promer94 in #4184
strictServerPrefetchWarning by @shuding in #4183Full Changelog: v2.3.6...v2.3.7
fix: do not error when not enabled during suspense by @huozhi in #4156
Full Changelog: v2.3.5...v2.3.6
perf: optimize useSWRConfig with useMemo to maintain stable reference by @samuel871211 in https://github.com/vercel/swr/pull/4110 https://github.com/v
useSWRConfig with useMemo to maintain stable reference by @samuel871211 in https://github.com/vercel/swr/pull/4110
https://github.com/vercel/swr/pull/4076PublicConfiguration.onDiscarded tsdoc with SWR official website by @samuel871211 inFull Changelog: https://github.com/vercel/swr/compare/v2.3.4...v2.3.5
perf: optimize useSWRConfig with useMemo to maintain stable reference by @samuel871211 in https://github.com/vercel/swr/pull/4110
useSWRConfig with useMemo to maintain stable reference by @samuel871211 in https://github.com/vercel/swr/pull/4110PublicConfiguration.onDiscarded tsdoc with SWR official website by @samuel871211 in https://github.com/vercel/swr/pull/4076Full Changelog: https://github.com/vercel/swr/compare/v2.3.4...v2.3.5-beta.0
Fix markdown typo by @Nusab19 in https://github.com/vercel/swr/pull/4106
data type by @oosawy in https://github.com/vercel/swr/pull/4126Full Changelog: https://github.com/vercel/swr/compare/v2.3.3...v2.3.4
enhance: use empty prototype object by @huozhi in https://github.com/vercel/swr/pull/4099
Full Changelog: https://github.com/vercel/swr/compare/v2.3.2...v2.3.3
(fix) keepPreviousData: return fallback instead of undefined value by @dvoytenko in https://github.com/vercel/swr/pull/4087
Full Changelog: https://github.com/vercel/swr/compare/v2.3.1...v2.3.2
fix: missing throwOnError in SWRMutationHook options by @Ram4GB in https://github.com/vercel/swr/pull/3054
throwOnError in SWRMutationHook options by @Ram4GB in https://github.com/vercel/swr/pull/3054useSWRHandler by @samuel871211 in https://github.com/vercel/swr/pull/4075Full Changelog: https://github.com/vercel/swr/compare/v2.3.0...v2.3.1
fix: Replace the deprecated 'window' with 'globalThis' for Deno by @saul-atomrigs in https://github.com/vercel/swr/pull/2915
fallback by @shuding in https://github.com/vercel/swr/pull/3045Full Changelog: https://github.com/vercel/swr/compare/v2.2.5...v2.3.0
Nothing published for this version
fix: Improve comparison performance by @shuding in https://github.com/vercel/swr/pull/2973
Full Changelog: https://github.com/vercel/swr/compare/v2.2.6-beta.3...v2.2.6-beta.4
ci: fix ci error and upgrade action version by @promer94 in https://github.com/vercel/swr/pull/2952
Full Changelog: https://github.com/vercel/swr/compare/v2.2.6-beta.2...v2.2.6-beta.3
fix: Replace the deprecated 'window' with 'globalThis' for Deno by @saul-atomrigs in https://github.com/vercel/swr/pull/2915
Full Changelog: https://github.com/vercel/swr/compare/v2.2.6-beta.0...v2.2.6-beta.1
Nothing published for this version
types: isLoading typed as boolean when using fallbackData (#2866) by @yjrhgvbn in https://github.com/vercel/swr/pull/2875
Full Changelog: https://github.com/vercel/swr/compare/v2.2.4...v2.2.5
Revert "Remove index.js suffix of use-sync-external-store/shim to support React Native" by @huozhi in https://github.com/vercel/swr/pull/2802
index.js suffix of use-sync-external-store/shim to support React Native" by @huozhi in https://github.com/vercel/swr/pull/2802Full Changelog: https://github.com/vercel/swr/compare/v2.2.3...v2.2.4
fix: remove permissive type by @wcatron in https://github.com/vercel/swr/pull/2759
index.js suffix of use-sync-external-store/shim to support React Native by @malash in https://github.com/vercel/swr/pull/2767Full Changelog: https://github.com/vercel/swr/compare/v2.2.2...v2.2.3
fix: It should use startTransition only when IS_REACT_LEGACY is false by @TopGrd in https://github.com/vercel/swr/pull/2756
ArgumentsTuple by @Andarist in https://github.com/vercel/swr/pull/2761Full Changelog: https://github.com/vercel/swr/compare/v2.2.1...v2.2.2
Add use client directive for client components exports by @huozhi in https://github.com/vercel/swr/pull/2696
revalidate to support parallel option by @promer94 in https://github.com/vercel/swr/pull/2727Full Changelog: https://github.com/vercel/swr/compare/v2.2.0...v2.2.1
Nothing published for this version
Nothing published for this version
fix: Add use client directive for client components exports by @huozhi in https://github.com/vercel/swr/pull/2696
Full Changelog: https://github.com/vercel/swr/compare/v2.2.0...v2.2.1-beta.1
Nothing published for this version
feat: use React.use API by @himself65 in https://github.com/vercel/swr/pull/2596
React.use API by @himself65 in https://github.com/vercel/swr/pull/2596startTransition so mutation hook could update immediately by @promer94 in https://github.com/vercel/swr/pull/2654useSWRMutation type. by @promer94 in https://github.com/vercel/swr/pull/2604Full Changelog: https://github.com/vercel/swr/compare/v2.1.5...v2.2.0
Revert "fix: remove startTransition so mutation hook could update immediately (#2654)" by @huozhi in https://github.com/vercel/swr/pull/2681
Full Changelog: https://github.com/vercel/swr/compare/v2.2.0-beta.4...v2.2.0-beta.5
build: fix conflict types for index and index.react-server by @huozhi in https://github.com/vercel/swr/pull/2677
Full Changelog: https://github.com/vercel/swr/compare/v2.2.0-beta.3...v2.2.0-beta.4
Fix Conditional Typing in useSWRMutation to Allow Optional ExtraArg Without Explicitly Passing Undefined by @saengmotmi in https://github.com/vercel/s
Full Changelog: https://github.com/vercel/swr/compare/v2.2.0-beta.2...v2.2.0-beta.3
Fix mutation types order by @huozhi in https://github.com/vercel/swr/pull/2669
Full Changelog: https://github.com/vercel/swr/compare/v2.2.0-beta.1...v2.2.0-beta.2
fix: do unsubscribe synchronously by @promer94 in https://github.com/vercel/swr/pull/2648
startTransition so mutation hook could update immediately by @promer94 in https://github.com/vercel/swr/pull/2654Full Changelog: https://github.com/vercel/swr/compare/v2.2.0-beta.0...v2.2.0-beta.1
test: add a new test setting to run tests with build files by @koba04 in https://github.com/vercel/swr/pull/2583
React.use API by @Himself65 in https://github.com/vercel/swr/pull/2596useSWRMutation type. by @promer94 in https://github.com/vercel/swr/pull/2604Full Changelog: https://github.com/vercel/swr/compare/v2.1.5...v2.2.0-beta.0
fix: missing interop helpers in bundle by @huozhi in https://github.com/vercel/swr/pull/2582
Full Changelog: https://github.com/vercel/swr/compare/v2.1.4...v2.1.5
Upgrade bundler by @huozhi in https://github.com/vercel/swr/pull/2557
Full Changelog: https://github.com/vercel/swr/compare/v2.1.3...v2.1.4
Fix #2548: pass origin key to subcription callback by @Zheaoli in https://github.com/vercel/swr/pull/2550
Data for useSWRSubscriptionOptions by @promer94 in https://github.com/vercel/swr/pull/2551Full Changelog: https://github.com/vercel/swr/compare/v2.1.2...v2.1.3
Improved type inferring for swr/subscription
swr/subscriptionSWRSubscriptionOptions type for swr/subscriptionuseSWRSubscription types by @promer94 in https://github.com/vercel/swr/pull/2535Full Changelog: https://github.com/vercel/swr/compare/v2.1.1...v2.1.2
refactor: remove useless dataRef, always compare cached data by @promer94 in https://github.com/vercel/swr/pull/2431
data type for default SWRConfig generic type by @connorch in https://github.com/vercel/swr/pull/2506Full Changelog: https://github.com/vercel/swr/compare/v2.1.0...v2.1.1
Subscription mode by @huozhi in https://github.com/vercel/swr/pull/1263
Checkout subscription docs and useSWRInfinite parallel fetching docs for more details
Full Changelog: https://github.com/vercel/swr/compare/v2.0.4...v2.1.0
build: fix release job condition by @huozhi in https://github.com/vercel/swr/pull/2392
Full Changelog: https://github.com/vercel/swr/compare/v2.0.3...v2.0.4
fix: parameters passed to subscribe is inconsistent with its declaration by @hong24 in https://github.com/vercel/swr/pull/2353
- characters in README.md by @JanKaifer in https://github.com/vercel/swr/pull/2334Full Changelog: https://github.com/vercel/swr/compare/v2.0.2...v2.0.3
fix: delay revalidation if a key is already active and has error by @promer94 in https://github.com/vercel/swr/pull/2338
Full Changelog: https://github.com/vercel/swr/compare/v2.0.1...v2.0.2
In this patch release, we majorly improved typing support and SWR can infer the types based on the configuration.
In this patch release, we majorly improved typing support and SWR can infer the types based on the configuration.
suspense option is true, the returned data will exclude undefined and the isLoading will always be false.fallbackData option is provided, the returned data will be the same type of fallbackData, and the isLoading will always be false.Here's a demo for it:
https://user-images.githubusercontent.com/4800338/213288879-ffbeeeb5-aca5-4a65-8229-69fbf9b0bf70.mp4
Full Changelog: https://github.com/vercel/swr/compare/2.0.0...v2.0.1
We are excited to announce the release of SWR 2.0! The new version comes with a lot of improvements:
We are excited to announce the release of SWR 2.0! The new version comes with a lot of improvements:
And more!
Read our blog post and migration guide: https://swr.vercel.app/blog/swr-v2
isLoading state and refactor the core by @shuding in https://github.com/vercel/swr/pull/1928keepPreviousData option by @shuding in https://github.com/vercel/swr/pull/1929throwOnError option by @shuding in https://github.com/vercel/swr/pull/2182Full Changelog: https://github.com/vercel/swr/compare/1.2.2...2.0.0
Fix missing esmodule mark in cjs build by @huozhi in https://github.com/vercel/swr/pull/2251
Full Changelog: https://github.com/vercel/swr/compare/2.0.0-rc.1...2.0.0-rc.3
Nothing published for this version
~~The last RC before SWR 2.0.~~ This release includes several small fixes with one breaking change.
The last RC before SWR 2.0. This release includes several small fixes with one breaking change.
In this release, we are dropping IE 11 support, and using ES2018 as the build target. However, when using SWR in a framework or using a bundler (esbuild, Webpack, etc.), you can still target ES5 or using a browserlist configuration to customize this.
The benefit of this change is, we can now use faster native APIs to make SWR more performant, instead of using old alternatives. A benchmark shows a 4.7x speed improvement of the useSWR() function call during SSR, when we change Object.assign({}, a, b) to { ...a, ...b }.
Details can be found in #2249.
Full Changelog: https://github.com/vercel/swr/compare/2.0.0-rc.0...2.0.0-rc.1
The SWR 2.0 release candidate. This RC has one breaking change, a new option for mutation APIs, and some bug fixes & improvements.
The SWR 2.0 release candidate. This RC has one breaking change, a new option for mutation APIs, and some bug fixes & improvements.
A failed mutation will not cause useSWR's error to be updated:
const { error, mutate } = useSWR('/api/user', getUser)
return <button onClick={async () => {
try {
await mutate(updateUser)
} catch (mutationError) {
// `mutationError` will not cause `error` to be updated.
}
}}>Update User</button>
In 2.0, with the example above, error will only be coming from getUser and will be shared across all useSWR('/api/user') hooks. And mutation errors (mutationError) will be coming from mutations like updateUser calls, they will be separated from fetcher errors.
There is also a new option throwOnError for useSWRMutation to disable the default throwing behavior of trigger:
const { trigger } = useSWRMutation('/api/user', updateUser)
try {
await trigger()
} catch (err) {
// ... it throws when failed to trigger the mutation so you can
// easily change the flow here
}
const { trigger, error } = useSWRMutation('/api/user', updateUser, {
throwOnError: false
})
// You don't need to try-catch here, you can instead handle errors
// on the component level in a declarative way
await trigger()
Read more about this change in #2182.
throwOnError option by @shuding in https://github.com/vercel/swr/pull/2182Full Changelog: https://github.com/vercel/swr/compare/2.0.0-beta.7...2.0.0-rc.0
Most changes in this release are maintenance related, as we are finalizing everything for the upcoming 2.0 stable version.
Most changes in this release are maintenance related, as we are finalizing everything for the upcoming 2.0 stable version.
Full Changelog: https://github.com/vercel/swr/compare/2.0.0-beta.6...2.0.0-beta.7
fix: Fix typos by @hiro0218 in https://github.com/vercel/swr/pull/2052
Full Changelog: https://github.com/vercel/swr/compare/2.0.0-beta.5...2.0.0-beta.6
You can now pass a filter function to the global mutate API to match any keys and mutate them together:
You can now pass a filter function to the global mutate API to match any keys and mutate them together:
import { mutate } from 'swr'
// Or from the hook if you customized the cache provider:
// { mutate } = useSWRConfig()
mutate(
key => typeof key === 'string' && key.startsWith('/api/item?id='),
data => update(data),
true
)
This action will match all keys starting with '/api/item?id=', and replace their data with update, then re-fetch after the mutation. The signature is the same as the current mutate API:
mutate(
'/api/item?id=123',
data => update(data),
true
)
The only difference is if you pass a function instead of a specific key, SWR will use it to match and mutate all the data in the cache. It will be convenient to use this to batch updates, or mutate keys by pattern.
Worth noting that it works with any key types, too:
useSWR(['item', 123], ...)
useSWR(['item', 124], ...)
useSWR(['item', 125], ...)
mutate(
key => Array.isArray(key) && key[0] === 'item',
undefined,
false
)
The mutation above will match all 3 keys and set the values to undefined (clear them), and skip the revalidation at the end. So another technique is to clear everything with this (e.g. when logging out):
mutate(
() => true,
undefined,
false
)
More use cases and discussions can be found in the original RFC: #1946.
Full Changelog: https://github.com/vercel/swr/compare/2.0.0-beta.4...2.0.0-beta.5
SWR now has a preload API that you can call programmatically to kick off the request early. For example, you can do preload('/api/user', fetcher) even
SWR now has a preload API that you can call programmatically to kick off the request early. For example, you can do preload('/api/user', fetcher) even outside of React:
import { useState } from 'react'
import useSWR, { preload } from 'swr'
const fetcher = (url) => fetch(url).then((res) => res.json())
// Preload the resource before rendering the User component below,
// this prevents potential waterfalls in your application.
// You can also start preloading when hovering the button or link, too.
preload('/api/user', fetcher)
function User() {
const { data } = useSWR('/api/user', fetcher)
...
}
export default function App() {
const [show, setShow] = useState(false)
return (
<div>
<button onClick={() => setShow(true)}>Show User</button>
{show ? <User /> : null}
</div>
)
}
So at the moment of clicking the button and actually rendering the User component, the resource is likely loaded already. If the request depends on some props or states, you can also preload it when hovering the button:
function App({ userId }) {
const [show, setShow] = useState(false)
return (
<div>
<button
onClick={() => setShow(true)}
onHover={() => preload('/api/user?id=' + userId, fetcher)}
>
Show User
</button>
{show ? <User /> : null}
</div>
)
}
Demo: https://codesandbox.io/s/swr-preloading-14bikv?file=/src/App.js
SWRConfig value (#2024)A new way to extend the SWR global configuration:
<SWRConfig value={{ revalidateOnFocus: false, dedupingInterval: 5000 }}>
<div>
<Header/>
<SWRConfig value={config => ({ ...config, dedupingInterval: 1000 })}>
<Main />
</SWRConfig>
</div>
</SWRConfig>
Where you can inherit the parent configuration and override the dedupingInterval value, but reuse the other options.
SWRConfig.default → SWRConfig.defaultValue (#2023)This is a currently undocumented API, but planned to go stable with the 2.0 release. You can access to SWR’s default options via the SWRConfig.defaultValue static and read-only property.
Full Changelog: https://github.com/vercel/swr/compare/2.0.0-beta.3...2.0.0-beta.4
_This is a change of SWR's internal implementation detail. For developers that use SWR, it will just work out of the box without any changes in their
This is a change of SWR's internal implementation detail. For developers that use SWR, it will just work out of the box without any changes in their apps.
Brought to you by @promer94 and @shuding, this release includes a core refactoring that improves React 18 support by adopting APIs like useSyncExternalStore and startTransition internally. Especially when rendering UIs concurrently with React 18, this new SWR version ensures stronger UI consistency.
Worth note that the current stable 1.x version of SWR still works well in React 18.
This core change isn't breaking and does not affect React <=17 apps.
When using suspense: true with SWR on the server-side (including pre-rendering in Next.js), it's now required to provide the initial data via fallbackData or fallback. This means that you can't use Suspense to fetch data on the server side as of today, but either doing fully client-side data fetching, or fetch the data via the framework (such as getStaticProps in Next.js).
While Suspense for libraries is still experimental, this behavior might change before the 2.0 stable release. More discussions can be found here: #1906.
Full Changelog: https://github.com/vercel/swr/compare/2.0.0-beta.1...2.0.0-beta.3
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →