useLazyFetch

This wrapper around useFetch triggers navigation immediately.

useLazyFetch provides a wrapper around useFetch that triggers navigation before the handler is resolved by setting the lazy option to true.

By default, useFetch blocks navigation until its async handler is resolved. useLazyFetch allows navigation to proceed immediately, with data being fetched in the background.

Usage

[app/pages/index.vue]

<script setup lang="ts">
const { status, data: posts } = await useLazyFetch('/api/posts')
</script>

<template>
  <div v-if="status === 'pending'">
    Loading ...
  </div>
  <div v-else>
    <div v-for="post in posts">
      <!-- do something -->
    </div>
  </div>
</template>

useLazyFetch has the same signature as useFetch.

Awaiting useLazyFetch only ensures the call is initialized. On client-side navigation, data may not be immediately available, and you must handle the pending state in your component’s template.

useLazyFetch is a reserved function name transformed by the compiler, so you should not name your own function useLazyFetch.

Parameters

useLazyFetch accepts the same parameters as useFetch:

url · string | Request | Ref<string | Request> | (() => string | Request) · required

The URL or request to fetch.

options · UseFetchOptions<T>

Same as useFetch options, with lazy automatically set to true. See useFetch parameters for full details.

Return Values

Returns the same AsyncData object as useFetch:

data · Ref<T | undefined>

The result of the asynchronous fetch.

refresh · (opts?: AsyncDataExecuteOptions) => Promise<void>

Function to manually refresh the data.

execute · (opts?: AsyncDataExecuteOptions) => Promise<void>

Alias for refresh.

error · Ref<Error | undefined>

Error object if the data fetching failed.

status · Ref<'idle' | 'pending' | 'success' | 'error'>

Status of the data request.

clear · () => void

Resets data to undefined, error to undefined, sets status to idle, and cancels any pending requests.

Examples

Handling Pending State

[app/pages/index.vue]

<script setup lang="ts">
/* Navigation will occur before fetching is complete.
 * Handle 'pending' and 'error' states directly within your component's template
 */
const { status, data: posts } = await useLazyFetch('/api/posts')
watch(posts, (newPosts) => {
  // Because posts might start out null, you won't have access
  // to its contents immediately, but you can watch it.
})
</script>

<template>
  <div v-if="status === 'pending'">
    Loading ...
  </div>
  <div v-else>
    <div v-for="post in posts">
      <!-- do something -->
    </div>
  </div>
</template>

Type

export function useLazyFetch<DataT, ErrorT> (
  url: string | Request | Ref<string | Request> | (() => string | Request),
  options?: UseFetchOptions<DataT>,
): Promise<AsyncData<DataT, ErrorT>>

useLazyFetch is equivalent to useFetch with lazy: true option set.