API

const { data, error, isLoading, isValidating, mutate } = useSWRV(key, fetcher, options);

TIP

useSWRV is a composable. Real calls belong inside setup() or <script setup>. The signature above is reference syntax, not a standalone script.

TIP

Coming from swrv@1? Start with Migrate from v1. The biggest migration points are SWRVConfig-based cache ownership, new mutate semantics, preload replacing mutate(key, promise) prefetching, and the removal of ttl, serverTTL, and revalidateDebounce.

Parameters

• key: a unique key for the request. It can be a string, tuple, object, ref, computed ref, function, or a falsy value such as null (details), (advanced usage)
• fetcher: optional. A function that returns the data for the given key (details)
• options: optional. A configuration object for this composable call (global defaults)

Return values

• data: a Vue ref containing the resolved data for the key
• error: a Vue ref containing the last error thrown by the fetcher
• isLoading: a Vue ref that is true when a request is in flight and there is no loaded data yet
• isValidating: a Vue ref that is true whenever a request or revalidation is in flight
• mutate(data?, options?): a bound mutation function for the current key (details)

fallbackData and keepPreviousData can give you something to render while isLoading remains true. This matches SWR’s idea that “loaded data” means resolved data for the active key, not placeholder data.

More information can be found in Understanding SWRV.

Options

• fetcher(args): fetcher function for this composable call (details)
• revalidateIfStale = true: revalidate on activation when cached data exists (details)
• revalidateOnMount: explicitly enable or disable the first activation revalidation (details)
• revalidateOnFocus = true: revalidate when the window regains focus (details)
• revalidateOnReconnect = true: revalidate when the browser comes back online (details)
• refreshInterval = 0: polling interval in milliseconds, or a function of the latest data (details)
• refreshWhenHidden = false: keep polling when the document is hidden
• refreshWhenOffline = false: keep polling when the browser is offline
• shouldRetryOnError = true: retry after fetcher errors (details)
• dedupingInterval = 2000: dedupe requests for the same key during this window
• focusThrottleInterval = 5000: throttle focus-triggered revalidation
• loadingTimeout = 3000: timeout for onLoadingSlow
• errorRetryInterval = 5000: delay between retries
• errorRetryCount: maximum number of retries
• fallback: key-value object for config-level fallback data (details), (SSR)
• fallbackData: fallback data for this composable call only (details)
• strictServerPrefetchWarning = false: warn during SSR when a key is rendered without prefetched data (details)
• keepPreviousData = false: keep the previous key’s data while the new key loads (details)
• onLoadingSlow(key, config): callback when a request takes too long
• onSuccess(data, key, config): callback when a request succeeds
• onError(error, key, config): callback when a request fails (details)
• onErrorRetry(error, key, config, revalidate, options): customize retry behavior (details)
• onDiscarded(key): callback when a stale response is discarded
• compare(a, b): comparison function used to preserve data identity (details)
• isPaused(): pause revalidation and ignore incoming results while paused
• isVisible(): custom visibility source
• isOnline(): custom online-state source
• use: middleware array (details)

Provider-level options such as client, cache, provider, initFocus, and initReconnect belong on SWRVConfig, not per-composable calls.

Companion APIs

The root swrv package exports:

• default and useSWRV
• SWRVConfig
• useSWRVConfig
• mutate
• preload
• createSWRVClient
• createCache
• unstable_serialize
• serializeSWRVSnapshot
• hydrateSWRVSnapshot

SWRVConfig

<SWRVConfig :value="{ fetcher, fallback, client }">
  <App />
</SWRVConfig>

Use SWRVConfig to provide shared fetchers, fallback data, middleware, and cache boundaries. The value prop can be either an object or a function that receives the parent configuration.

useSWRVConfig

const { cache, client, config, mutate, preload } = useSWRVConfig();

Use this inside setup() when you need the active scoped helpers instead of the root helpers.

mutate

await mutate(key, data?, options?);

mutate supports:

• bound and global mutation
• optimistic updates
• populateCache
• rollbackOnError
• boolean or function revalidate
• filter-based mutation across multiple keys

See Mutation.

preload

await preload(key, fetcher);

preload starts a request before a component using useSWRV consumes it. It dedupes by serialized key and is consumed by the first matching request. See Prefetching.

unstable_serialize

const serializedKey = unstable_serialize(key);

Use this when you need the exact serialized cache key, most commonly for fallback maps, snapshot data, or advanced infinite-cache operations.

Snapshot helpers

const snapshot = serializeSWRVSnapshot(client);
const hydratedClient = hydrateSWRVSnapshot(createSWRVClient(), snapshot);

These helpers are for SSR handoff. See Server rendering and hydration.

swrv/immutable

import useSWRVImmutable from "swrv/immutable";

This keeps the same call shape as useSWRV, but disables stale revalidation, focus revalidation, reconnect revalidation, and polling.

swrv/infinite

const { data, error, isLoading, isValidating, mutate, size, setSize } = useSWRVInfinite(
  getKey,
  fetcher,
  options,
);

Use this for infinite loading and paginated page arrays. It also exports unstable_serialize. See Pagination.

swrv/mutation

const { data, error, isMutating, reset, trigger } = useSWRVMutation(key, fetcher, options);

Use this for imperative remote writes with dedicated mutation state. See Mutation.

swrv/subscription

const { data, error } = useSWRVSubscription(key, subscribe, options);

Use this for real-time sources that push values through a disposer-based subscription contract. See Subscription.

Both forms disable automatic focus and reconnect revalidation.

Internal Entry Point

swrv/_internal is exported for advanced consumers who explicitly want the rebuild's lower-level helpers. It is available, but it should not be treated as the primary app-facing API.