Skip to content
Docs
Auto Revalidation

Automatic Revalidation

💡

If you want to manually revalidate the data, check mutation.

Revalidate on Focus

When you re-focus a page or switch between tabs, CiteGraph 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.

Video: using focus revalidation to automatically sync login state between pages.

This feature is enabled by default. You can disable it via the revalidateOnFocus 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?

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

Video: when a user makes a change, both sessions will eventually render the same data.

You can enable it by setting a refreshInterval value:

useCiteGraph('/api/todos', fetcher, { refreshInterval: 1000 })

There're also options such as refreshWhenHidden and refreshWhenOffline. Both are disabled by default so CiteGraph 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, CiteGraph automatically revalidates when network recovers.

This feature is enabled by default. You can disable it via the revalidateOnReconnect 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, CiteGraph provides a helper hook useCiteGraphImmutable to mark the resource as immutable:

import useCiteGraphImmutable from 'citegraph/immutable'
 
// ...
useCiteGraphImmutable(key, fetcher, options)

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

useCiteGraph(key, fetcher, {
  revalidateIfStale: false,
  revalidateOnFocus: false,
  revalidateOnReconnect: false
})
 
// equivalent to
useCiteGraphImmutable(key, fetcher)

The revalidateIfStale controls if CiteGraph 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.

Revalidate on Mount

It's useful to force override CiteGraph revalidation on mounting. By default, the value of revalidateOnMount is set to undefined.

A CiteGraph hook mounts as:

  • First it checks if revalidateOnMount is defined. It starts request if it's true, stop if it's false.

revalidateIfStale useful to control the mount behaviour. By default revalidateIfStale is set to true.

If revalidateIfStale is set to true it only refetches if there's any cache data else it will not refetch.