- Composables
- Components
- Utils
- Advanced
- Commands
- Configuration
useAsyncData
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 a setup function, plugin, or route middleware. 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.
Type
functionuseAsyncData(handler: (nuxtApp?:NuxtApp)=>Promise<DataT>,options?:AsyncDataOptions<DataT>):AsyncData<DataT>functionuseAsyncData(key:string,handler: (nuxtApp?:NuxtApp)=>Promise<DataT>,options?:AsyncDataOptions<DataT>):Promise<AsyncData<DataT>>typeAsyncDataOptions<DataT>= {server?:booleanlazy?:booleandefault?: ()=>DataT|Ref<DataT>|nulltransform?: (input:DataT)=>DataTpick?:string[]watch?:WatchSource[]immediate?:boolean}typeAsyncData<DataT,ErrorT>= {data:Ref<DataT|null>pending:Ref<boolean>refresh: (opts?:AsyncDataExecuteOptions)=>Promise<void>execute: (opts?:AsyncDataExecuteOptions)=>Promise<void>error:Ref<ErrorT|null>status:Ref<AsyncDataRequestStatus>};interfaceAsyncDataExecuteOptions {dedupe?:boolean}typeAsyncDataRequestStatus='idle'|'pending'|'success'|'error'Params
- key: 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
useAsyncDatawill be generated for you. - handler: an asynchronous function that returns a value
- options:
- lazy: whether to resolve the async function after loading the route, instead of blocking client-side navigation (defaults to
false) - default: a factory function to set the default value of the data, before the async function resolves - particularly useful with the
lazy: trueoption - server: whether to fetch the data on the server (defaults to
true) - transform: a function that can be used to alter
handlerfunction result after resolving - pick: only pick specified keys in this array from the
handlerfunction result - watch: watch reactive sources to auto-refresh
- immediate: When set to
false, will prevent the request from firing immediately. (defaults totrue)
- lazy: whether to resolve the async function after loading the route, instead of blocking client-side navigation (defaults to
Under the hood,lazy: false uses<Suspense> to block the loading of the route before the data has been fetched. Consider usinglazy: true and implementing a loading state instead for a snappier user experience.
Return Values
- data: the result of the asynchronous function that is passed in.
- pending: a boolean indicating whether the data is still being fetched.
- refresh/execute: a function that can be used to refresh the data returned by the
handlerfunction. - error: an error object if the data fetching failed.
- status: a string indicating the status of the data request (
"idle","pending","success","error").
By default, Nuxt waits until arefresh is finished before it can be executed again.
If you have not fetched data on the server (for example, withserver: false), then the datawill not be fetched until hydration completes. This means even if you awaituseAsyncData on the client side,data will remainnull within<script setup>.
Example
const {data,pending,error,refresh }=awaituseAsyncData('mountains', ()=>$fetch('https://api.nuxtjs.dev/mountains'))Example with watching params change
The built-inwatch option allows automatically rerunning the fetcher function when any changes are detected.
constpage=ref(1)const {data:posts }=awaituseAsyncData('posts', ()=>$fetch('https://fakeApi.com/posts', {params: {page:page.value } }), {watch: [page] })useAsyncData is a reserved function name transformed by the compiler, so you should not name your own functionuseAsyncData.