useAsyncState
Reactive async state. Will not block your setup function and will trigger changes once the promise is ready. The state is a shallowRef
by default.
Demo
Ready: true
Loading: false
userId: 1
id: 1
title: delectus aut autem
completed: false
Usage
ts
import { useAsyncState } from '@vueuse/core'
import axios from 'axios'
const { state, isReady, isLoading } = useAsyncState(
axios
.get('https://jsonplaceholder.typicode.com/todos/1')
.then(t => t.data),
{ id: null },
)
Manually trigger the async function
You can also trigger it manually. This is useful when you want to control when the async function is executed.
vue
<script setup lang="ts">
import { useAsyncState } from '@vueuse/core'
const { state, execute, executeImmediate } = useAsyncState(action, '', { immediate: false })
async function action(event) {
await new Promise(resolve => setTimeout(resolve, 500))
return `${event.target.textContent} clicked!`
}
</script>
<template>
<p>State: {{ state }}</p>
<button class="button" @click="executeImmediate">
Execute now
</button>
<button class="ml-2 button" @click="event => execute(500, event.target)">
Execute with delay
</button>
</template>
Type Declarations
Show Type Declarations
typescript
export interface UseAsyncStateReturnBase<
Data,
Params extends any[],
Shallow extends boolean,
> {
state: Shallow extends true ? Ref<Data> : Ref<UnwrapRef<Data>>
isReady: Ref<boolean>
isLoading: Ref<boolean>
error: Ref<unknown>
execute: (delay?: number, ...args: Params) => Promise<Data>
executeImmediate: (...args: Params) => Promise<Data>
}
export type UseAsyncStateReturn<
Data,
Params extends any[],
Shallow extends boolean,
> = UseAsyncStateReturnBase<Data, Params, Shallow> &
PromiseLike<UseAsyncStateReturnBase<Data, Params, Shallow>>
export interface UseAsyncStateOptions<Shallow extends boolean, D = any> {
/**
* Delay for the first execution of the promise when "immediate" is true. In milliseconds.
*
* @default 0
*/
delay?: number
/**
* Execute the promise right after the function is invoked.
* Will apply the delay if any.
*
* When set to false, you will need to execute it manually.
*
* @default true
*/
immediate?: boolean
/**
* Callback when error is caught.
*/
onError?: (e: unknown) => void
/**
* Callback when success is caught.
* @param {D} data
*/
onSuccess?: (data: D) => void
/**
* Sets the state to initialState before executing the promise.
*
* This can be useful when calling the execute function more than once (for
* example, to refresh data). When set to false, the current state remains
* unchanged until the promise resolves.
*
* @default true
*/
resetOnExecute?: boolean
/**
* Use shallowRef.
*
* @default true
*/
shallow?: Shallow
/**
*
* An error is thrown when executing the execute function
*
* @default false
*/
throwError?: boolean
}
/**
* Reactive async state. Will not block your setup function and will trigger changes once
* the promise is ready.
*
* @see https://vueuse.org/useAsyncState
* @param promise The promise / async function to be resolved
* @param initialState The initial state, used until the first evaluation finishes
* @param options
*/
export declare function useAsyncState<
Data,
Params extends any[] = any[],
Shallow extends boolean = true,
>(
promise: Promise<Data> | ((...args: Params) => Promise<Data>),
initialState: Data,
options?: UseAsyncStateOptions<Shallow, Data>,
): UseAsyncStateReturn<Data, Params, Shallow>