jsschools

useAsyncData()

Resolves async data in a SSR-safe way using a custom handler function.

Since Nuxt 3.0 Spec ↗

Syntax

const { data, error, status, refresh } = await useAsyncData(key, handler, options)

Parameters

NameTypeRequiredDescription
key string No A unique key that dedupes requests and caches the result across server and client. Auto-generated from the call site if omitted.
handler (ctx) => Promise<T> Yes An async function returning the data. Should return a truthy or well-defined value (avoid returning undefined).
options object No `server`, `lazy`, `default`, `transform`, `pick`, `watch`, `immediate`, `deep`, `dedupe`, and `getCachedData`.

Returns

AsyncData<DataT, ErrorT> — Reactive data, error, status, pending, refresh, execute, clear.

Examples

<script setup lang="ts">
const { data: user } = await useAsyncData('me', () =>
  $fetch('/api/me')
)
</script>

<script setup lang="ts">
// Combine multiple requests into one payload entry
const { data } = await useAsyncData('dashboard', async () => {
  const [stats, feed] = await Promise.all([
    $fetch('/api/stats'),
    $fetch('/api/feed'),
  ])
  return { stats, feed }
})
</script>

<script setup lang="ts">
const route = useRoute()
const { data, refresh } = await useAsyncData(
  () => `post-${route.params.id}`,
  () => $fetch(`/api/posts/${route.params.id}`),
  { watch: [() => route.params.id] }
)
</script>

Notes

Use `useAsyncData` when you need custom fetching logic, multiple requests, or non-`$fetch` sources (e.g. a CMS SDK). `useFetch` is sugar over this. The handler runs on the server during SSR and the result is hydrated on the client without re-running. Provide `getCachedData` to reuse Nuxt payload/cache between navigations.

See also