--- title: Mutation & Revalidation type: guide summary: Mutate cached data and trigger revalidation. prerequisites: - /docs/data-fetching related: - /docs/data-fetching - /docs/revalidation --- # Mutation & Revalidation SWR provides the [`mutate`](/docs/mutation#mutate) and [`useSWRMutation`](/docs/mutation#useswrmutation) APIs for mutating remote data and related cache. ## `mutate` There're 2 ways to use the `mutate` API to mutate the data, the global mutate API which can mutate any key and the bound mutate API which only can mutate the data of corresponding SWR hook. #### Global Mutate The recommended way to get the global mutator is to use the [`useSWRConfig`](/docs/global-configuration#access-to-global-configurations) hook: ```js import { useSWRConfig } from "swr" function App() { const { mutate } = useSWRConfig() mutate(key, data, options) } ``` You can also import it globally: ```js import { mutate } from "swr" function App() { mutate(key, data, options) } ``` Using global mutator only with the `key` parameter will ***not update the cache or trigger revalidation*** unless there is a mounted SWR hook using the same key. #### Bound Mutate Bound mutate is the short path to mutate the current key with data. Which `key` is bounded to the `key` passing to `useSWR`, and receive the `data` as the first argument. It is functionally equivalent to the global `mutate` function in the previous section but does not require the `key` parameter: ```jsx import useSWR from 'swr' function Profile () { const { data, mutate } = useSWR('/api/user', fetcher) return (

My name is {data.name}.

) } ``` #### Revalidation When you call `mutate(key)` (or just `mutate()` with the bound mutate API) without any data, it will trigger a revalidation (mark the data as expired and trigger a refetch) for the resource. This example shows how to automatically refetch the login info (e.g. inside ``) when the user clicks the “Logout” button: ```jsx {14} import useSWR, { useSWRConfig } from 'swr' function App () { const { mutate } = useSWRConfig() return (
) } ``` It broadcasts to SWR hooks under the same [cache provider](/docs/advanced/cache) scope. If no cache provider exists, it will broadcast to all SWR hooks. ### API #### Parameters * `key`: same as `useSWR`'s `key`, but a function behaves as [a filter function](/docs/mutation#mutate-multiple-items) * `data`: data to update the client cache, or an async function for the remote mutation * `options`: accepts the following options * `optimisticData`: data to immediately update the client cache, or a function that receives current data and returns the new client cache data, usually used in optimistic UI. * `revalidate = true`: should the cache revalidate once the asynchronous update resolves. If set to a function, the function receives `data` and `key`. * `populateCache = true`: should the result of the remote mutation be written to the cache, or a function that receives new result and current result as arguments and returns the mutation result. * `rollbackOnError = true`: should the cache rollback if the remote mutation errors, or a function that receives the error thrown from fetcher as arguments and returns a boolean whether should rollback or not. * `throwOnError = true`: should the mutate call throw the error when fails. #### Return Values `mutate` returns the results the `data` parameter has been resolved. The function passed to `mutate` will return an updated data which is used to update the corresponding cache value. If there is an error thrown while executing the function, the error will be thrown so it can be handled appropriately. ```jsx try { const user = await mutate('/api/user', updateUser(newUser)) } catch (error) { // Handle an error while updating the user here } ``` ## `useSWRMutation` SWR also provides `useSWRMutation` as a hook for remote mutations. The remote mutations are only triggered manually, instead of automatically like `useSWR`. Also, this hook doesn’t share states with other `useSWRMutation` hooks. ```tsx import useSWRMutation from 'swr/mutation' // Fetcher implementation. // The extra argument will be passed via the `arg` property of the 2nd parameter. // In the example below, `arg` will be `'my_token'` async function updateUser(url, { arg }: { arg: string }) { await fetch(url, { method: 'POST', headers: { Authorization: `Bearer ${arg}` } }) } function Profile() { // A useSWR + mutate like API, but it will not start the request automatically. const { trigger } = useSWRMutation('/api/user', updateUser, options) return } ``` ### API #### Parameters * `key`: same as [`mutate`](/docs/mutation#mutate)'s `key` * `fetcher(key, { arg })`: an async function for remote mutation * `options`: an optional object with the following properties: * `optimisticData`: same as `mutate`'s `optimisticData` * `revalidate = true`: same as `mutate`'s `revalidate` * `populateCache = false`: same as `mutate`'s `populateCache`, but the default is `false` * `rollbackOnError = true`: same as `mutate`'s `rollbackOnError` * `throwOnError = true`: same as `mutate`'s `throwOnError` * `onSuccess(data, key, config)`:　 callback function when a remote mutation has been finished successfully * `onError(err, key, config)`: callback function when a remote mutation has returned an error #### Return Values * `data`: data for the given key returned from `fetcher` * `error`: error thrown by `fetcher` (or undefined) * `trigger(arg, options)`: a function to trigger a remote mutation * `reset`: a function to reset the state (`data`, `error`, `isMutating`) * `isMutating`: if there's an ongoing remote mutation ### Basic Usage ```tsx import useSWRMutation from 'swr/mutation' async function sendRequest(url, { arg }: { arg: { username: string }}) { return fetch(url, { method: 'POST', body: JSON.stringify(arg) }).then(res => res.json()) } function App() { const { trigger, isMutating } = useSWRMutation('/api/user', sendRequest, /* options */) return ( ) } ``` If you want to use the mutation results in rendering, you can get them from the return values of `useSWRMutation`. ```jsx const { trigger, data, error } = useSWRMutation('/api/user', sendRequest) ``` `useSWRMutation` shares a cache store with `useSWR`, so it can detect and avoid race conditions between `useSWR`. It also supports `mutate`'s functionalities like optimistic updates and rollback on errors. You can pass these options `useSWRMutation` and its `trigger` function. ```jsx const { trigger } = useSWRMutation('/api/user', updateUser, { optimisticData: current => ({ ...current, name: newName }) }) // or trigger(newName, { optimisticData: current => ({ ...current, name: newName }) }) ``` ### Defer loading data until needed You can also use `useSWRMutation` for loading data. `useSWRMutation` won't start requesting until `trigger` is called, so you can defer loading data when you actually need it. ```jsx import { useState } from 'react' import useSWRMutation from 'swr/mutation' const fetcher = url => fetch(url).then(res => res.json()) const Page = () => { const [show, setShow] = useState(false) // data is undefined until trigger is called const { data: user, trigger } = useSWRMutation('/api/user', fetcher); return (
{show && user ?
{user.name}
: null}
); } ``` ## Optimistic Updates In many cases, applying local mutations to data is a good way to make changes feel faster — no need to wait for the remote source of data. With the `optimisticData` option, you can update your local data manually, while waiting for the remote mutation to finish. Composing `rollbackOnError` you can also control when to rollback the data. ```jsx import useSWR, { useSWRConfig } from 'swr' function Profile () { const { mutate } = useSWRConfig() const { data } = useSWR('/api/user', fetcher) return (

My name is {data.name}.

) } ``` > The **`updateFn`** should be a promise or asynchronous function to handle the remote mutation, it should return updated data. You can also pass a function to `optimisticData` to make it depending on the current data: ```jsx import useSWR, { useSWRConfig } from 'swr' function Profile () { const { mutate } = useSWRConfig() const { data } = useSWR('/api/user', fetcher) return (

My name is {data.name}.

) } ``` You can also create the same thing with `useSWRMutation` and `trigger`: ```jsx import useSWRMutation from 'swr/mutation' function Profile () { const { trigger } = useSWRMutation('/api/user', updateUserName) return (

My name is {data.name}.

) } ``` ## Rollback on Errors When you have `optimisticData` set, it’s possible that the optimistic data gets displayed to the user, but the remote mutation fails. In this case, you can leverage `rollbackOnError` to revert the local cache to the previous state, to make sure the user is seeing the correct data. ## Update Cache After Mutation Sometimes, the remote mutation request directly returns the updated data, so there is no need to do an extra fetch to load it. You can enable the `populateCache` option to update the cache for `useSWR` with the response of the mutation: ```jsx const updateTodo = () => fetch('/api/todos/1', { method: 'PATCH', body: JSON.stringify({ completed: true }) }) mutate('/api/todos', updateTodo, { populateCache: (updatedTodo, todos) => { // filter the list, and return it with the updated item const filteredTodos = todos.filter(todo => todo.id !== '1') return [...filteredTodos, updatedTodo] }, // Since the API already gives us the updated information, // we don't need to revalidate here. revalidate: false }) ``` Or with the `useSWRMutation` hook: ```jsx useSWRMutation('/api/todos', updateTodo, { populateCache: (updatedTodo, todos) => { // filter the list, and return it with the updated item const filteredTodos = todos.filter(todo => todo.id !== '1') return [...filteredTodos, updatedTodo] }, // Since the API already gives us the updated information, // we don't need to revalidate here. revalidate: false }) ``` When combined with `optimisticData` and `rollbackOnError`, you’ll get a perfect optimistic UI experience. ## Avoid Race Conditions Both `mutate` and `useSWRMutation` can avoid race conditions between `useSWR`. For example, ```tsx function Profile() { const { data } = useSWR('/api/user', getUser, { revalidateInterval: 3000 }) const { trigger } = useSWRMutation('/api/user', updateUser) return <> {data ? data.username : null} } ``` The normal `useSWR` hook might refresh its data any time due to focus, polling, or other conditions. This way the displayed username can be as fresh as possible. However, since we have a mutation there that can happen at the nearly same time of a refetch of `useSWR`, there could be a race condition that `getUser` request starts earlier, but takes longer than `updateUser`. Luckily, `useSWRMutation` handles this for you automatically. After the mutation, it will tell `useSWR` to ditch the ongoing request and revalidate, so the stale data will never be displayed. ## Mutate Based on Current Data Sometimes, you want to update a part of your data based on the current data. With `mutate`, you can pass an async function which will receive the current cached value, if any, and returns an updated document. ```jsx mutate('/api/todos', async todos => { // let's update the todo with ID `1` to be completed, // this API returns the updated data const updatedTodo = await fetch('/api/todos/1', { method: 'PATCH', body: JSON.stringify({ completed: true }) }) // filter the list, and return it with the updated item const filteredTodos = todos.filter(todo => todo.id !== '1') return [...filteredTodos, updatedTodo] // Since the API already gives us the updated information, // we don't need to revalidate here. }, { revalidate: false }) ``` ## Mutate Multiple Items The global `mutate` API accepts a filter function, which accepts `key` as the argument and returns which keys to revalidate. The filter function is applied to all the existing cache keys: ```jsx 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='), undefined, { revalidate: true } ) ``` This also works with any key type like an array. The mutation matches all keys, of which the first element is `'item'`. ```jsx useSWR(['item', 123], ...) useSWR(['item', 124], ...) useSWR(['item', 125], ...) mutate( key => Array.isArray(key) && key[0] === 'item', undefined, { revalidate: false } ) ``` The filter function is applied to all existing cache keys, so you should not assume the shape of keys when using multiple shapes of keys. ```jsx // ✅ matching array key mutate((key) => key[0].startsWith('/api'), data) // ✅ matching string key mutate((key) => typeof key === 'string' && key.startsWith('/api'), data) // ❌ ERROR: mutate uncertain keys (array or string) mutate((key: any) => /\/api/.test(key.toString())) ``` You can use the filter function to clear all cache data, which is useful when logging out: ```js const clearCache = () => mutate( () => true, undefined, { revalidate: false } ) // ...clear cache on logout clearCache() ```