import Video from '@components/video'
import { Bleed } from 'nextra-theme-docs'
import { Callout } from 'nextra/components'

# Automatic Revalidation

<Callout>
  If you want to manually revalidate the data, check [mutation](/docs/mutation).
</Callout>

## Revalidate on Focus

When you re-focus a page or switch between tabs, SWR automatically revalidates
data.

This can be useful to immediately synchronize to the latest state. This is
helpful for refreshing data in scenarios like stale mobile tabs, or laptops that
**went to sleep**.

<Bleed>
  <Video
    src="https://raw.githubusercontent.com/vercel/swr-site/master/.github/videos/focus-revalidate.mp4"
    caption="Video: using focus revalidation to automatically sync login state between pages."
    ratio={307 / 768}
  />
</Bleed>

This feature is enabled by default. You can disable it via the
[`revalidateOnFocus`](/docs/options) option.

## Revalidate on Interval

In many cases, data changes because of multiple devices, multiple users,
multiple tabs. How can we over time update the data on screen?

SWR will give you the option to automatically refetch data. It’s **smart** which
means refetching will only happen if the component associated with the hook is
**on screen**.

<Bleed>
  <Video
    src="https://raw.githubusercontent.com/vercel/swr-site/master/.github/videos/refetch-interval.mp4"
    caption="Video: when a user makes a change, both sessions will eventually render the same data."
    ratio={307 / 768}
  />
</Bleed>

You can enable it by setting a [`refreshInterval`](/docs/options) value:

```js
useSWR('/api/todos', fetcher, { refreshInterval: 1000 })
```

There're also options such as `refreshWhenHidden` and `refreshWhenOffline`. Both
are disabled by default so SWR won't fetch when the webpage is not on screen, or
there's no network connection.

## Revalidate on Reconnect

It's useful to also revalidate when the user is back online. This scenario
happens a lot when the user unlocks their computer, but the internet is not yet
connected at the same moment.

To make sure the data is always up-to-date, SWR automatically revalidates when
network recovers.

This feature is enabled by default. You can disable it via the
[`revalidateOnReconnect`](/docs/options) option.

## Disable Automatic Revalidations

If the resource is **immutable**, that will never change if we revalidate again,
we can disable all kinds of automatic revalidations for it.

Since version 1.0, SWR provides a helper hook `useSWRImmutable` to mark the
resource as immutable:

```js
import useSWRImmutable from 'swr/immutable'

// ...
useSWRImmutable(key, fetcher, options)
```

It has the same API interface as the normal `useSWR` hook. You can also do the
same thing by disable the following revalidation options:

```js
useSWR(key, fetcher, {
  revalidateIfStale: false,
  revalidateOnFocus: false,
  revalidateOnReconnect: false
})

// equivalent to
useSWRImmutable(key, fetcher)
```

The `revalidateIfStale` controls if SWR should revalidate when it mounts and
there is stale data.

These 2 hooks above do the **exact same** thing. Once the data is cached, they
will never request it again.
