Skip to main content
Within your pages, components, and plugins you can use useAsyncData to get access to data that resolves asynchronously.
useAsyncData is a composable meant to be called directly in the Nuxt context. It returns reactive composables and handles adding responses to the Nuxt payload so they can be passed from server to client without re-fetching the data on client side when the page hydrates.

​
Usage

[app/pages/index.vue]
<script setup lang="ts">
const { data, status, pending, error, refresh, clear } = await useAsyncData(
  'mountains',
  (_nuxtApp, { signal }) => $fetch('https://api.nuxtjs.dev/mountains', { signal }),
)
</script>
data, status, pending and error are Vue refs and they should be accessed with .value when used within the <script setup>, while refresh/execute and clear are plain functions.

​
Parameters

​
key
string | Ref<string> | (() => string)
A unique key to ensure that data fetching can be properly de-duplicated across requests. If you do not provide a key, then a key that is unique to the file name and line number of the instance of useAsyncData will be generated for you. Can be reactive for dynamic data fetching.
​
handler
(nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<T>
required
An asynchronous function that must return a truthy value (for example, it should not be undefined or null) or the request may be duplicated on the client side. The handler function should be side-effect free to ensure predictable behavior during SSR and CSR hydration.
​
options
AsyncDataOptions<T>
Options to configure the behavior of useAsyncData.
​
server
boolean
default:"true"
Whether to fetch the data on the server.
​
lazy
boolean
default:"false"
Whether to resolve the async function after loading the route, instead of blocking client-side navigation.
​
immediate
boolean
default:"true"
When set to false, will prevent the request from firing immediately.
​
default
() => T | Ref<T>
A factory function to set the default value of the data, before the async function resolves - useful with the lazy: true or immediate: false option.
​
transform
(input: T) => T | Promise<T>
A function that can be used to alter handler function result after resolving.
​
getCachedData
(key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => T | undefined
Provide a function which returns cached data. An undefined return value will trigger a fetch.
​
pick
string[]
Only pick specified keys in this array from the handler function result.
​
watch
WatchSource[] | false
Watch reactive sources to auto-refresh. Set to false to disable watching.
​
deep
boolean
default:"false"
Return data in a deep ref object. It is false by default to return data in a shallow ref object, which can improve performance if your data does not need to be deeply reactive.
​
dedupe
'cancel' | 'defer'
default:"'cancel'"
Avoid fetching same key more than once at a time. cancel cancels existing requests when a new one is made. defer does not make new requests at all if there is a pending request.
​
timeout
number
A number in milliseconds to wait before timing out the request.

​
Return Values

​
data
Ref<T | undefined>
The result of the asynchronous function that is passed in.
​
refresh
(opts?: AsyncDataExecuteOptions) => Promise<void>
A function that can be used to refresh the data returned by the handler function. Also aliased as execute.
​
error
Ref<Error | undefined>
An error object if the data fetching failed.
​
status
Ref<'idle' | 'pending' | 'success' | 'error'>
A string indicating the status of the data request:
  • idle: when the request has not started
  • pending: the request is in progress
  • success: the request has completed successfully
  • error: the request has failed
​
pending
Ref<boolean>
A boolean that is true while the request is in progress (that is, while status.value === 'pending').
​
clear
() => void
A function that can be used to set data to undefined, set error to undefined, set status to idle, and mark any currently pending requests as cancelled.

​
Examples

​
Watch Params

The built-in watch option allows automatically rerunning the fetcher function when any changes are detected.
[app/pages/index.vue]
<script setup lang="ts">
const page = ref(1)
const { data: posts } = await useAsyncData(
  'posts',
  (_nuxtApp, { signal }) => $fetch('https://fakeApi.com/posts', {
    params: {
      page: page.value,
    },
    signal,
  }), {
    watch: [page],
  },
)
</script>

​
Reactive Keys

You can use a computed ref, plain ref or a getter function as the key, allowing for dynamic data fetching that automatically updates when the key changes:
[app/pages/[id].vue]
<script setup lang="ts">
const route = useRoute()
const userId = computed(() => `user-${route.params.id}`)

const { data: user } = useAsyncData(
  userId,
  () => fetchUserById(route.params.id),
)
</script>

​
Make your handler abortable

You can make your handler function abortable by using the signal provided in the second argument: 
const { data, error } = await useAsyncData(
  'users',
  (_nuxtApp, { signal }) => $fetch('/api/users', { signal }),
)

refresh() // will actually cancel the $fetch request (if dedupe: cancel)
refresh()

clear() // will cancel the latest pending handler

​
Type

export type AsyncDataHandler<ResT> = (
  nuxtApp: NuxtApp,
  options: { signal: AbortSignal }
) => Promise<ResT>

export function useAsyncData<DataT, DataE> (
  handler: AsyncDataHandler<DataT>,
  options?: AsyncDataOptions<DataT>,
): AsyncData<DataT, DataE>

export function useAsyncData<DataT, DataE> (
  key: MaybeRefOrGetter<string>,
  handler: AsyncDataHandler<DataT>,
  options?: AsyncDataOptions<DataT>,
): Promise<AsyncData<DataT, DataE>>

type AsyncDataOptions<DataT> = {
  server?: boolean
  lazy?: boolean
  immediate?: boolean
  deep?: boolean
  dedupe?: 'cancel' | 'defer'
  default?: () => DataT | Ref<DataT> | null
  transform?: (input: DataT) => DataT | Promise<DataT>
  pick?: string[]
  watch?: MultiWatchSources | false
  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
  timeout?: number
}

type AsyncData<DataT, ErrorT> = {
  data: Ref<DataT | undefined>
  refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>
  execute: (opts?: AsyncDataExecuteOptions) => Promise<void>
  clear: () => void
  error: Ref<ErrorT | undefined>
  status: Ref<AsyncDataRequestStatus>
  pending: Ref<boolean>
}