1---
2category: State
3---
4 
5# useAsyncState
6 
7Reactive async state. Will not block your setup function and will trigger changes once the promise is ready. The state is a `shallowRef` by default.
8 
9## Usage
10 
11```ts
12import { useAsyncState } from '@vueuse/core'
13import axios from 'axios'
14 
15const { state, isReady, isLoading, error } = useAsyncState(
16  axios
17    .get('https://jsonplaceholder.typicode.com/todos/1')
18    .then(t => t.data),
19  { id: null },
20)
21```
22 
23### Return Values
24 
25| Property           | Description                                         |
26| ------------------ | --------------------------------------------------- |
27| `state`            | The result of the async function                    |
28| `isReady`          | `true` when the promise has resolved at least once  |
29| `isLoading`        | `true` while the promise is pending                 |
30| `error`            | The error if the promise was rejected               |
31| `execute`          | Re-execute the async function with optional delay   |
32| `executeImmediate` | Re-execute immediately (shorthand for `execute(0)`) |
33 
34### Awaiting the Result
35 
36The return value is thenable, so you can await it in async functions or `<script setup>`:
37 
38```ts
39const { state, isReady } = await useAsyncState(fetchData, null)
40// `state` is now populated, `isReady` is true
41```
42 
43### Manual Execution
44 
45Set `immediate: false` to prevent automatic execution on creation.
46 
47```vue
48<script setup lang="ts">
49import { useAsyncState } from '@vueuse/core'
50 
51const { state, execute, executeImmediate } = useAsyncState(action, '', { immediate: false })
52 
53async function action(event) {
54  await new Promise(resolve => setTimeout(resolve, 500))
55  return `${event.target.textContent} clicked!`
56}
57</script>
58 
59<template>
60  <p>State: {{ state }}</p>
61 
62  <button class="button" @click="executeImmediate">
63    Execute now
64  </button>
65 
66  <button class="ml-2 button" @click="event => execute(500, event)">
67    Execute with delay
68  </button>
69</template>
70```
71 
72### Options
73 
74```ts
75const { state } = useAsyncState(promise, initialState, {
76  // Execute immediately on creation (default: true)
77  immediate: true,
78  // Delay before first execution in ms (default: 0)
79  delay: 0,
80  // Reset state to initial before each execution (default: true)
81  resetOnExecute: true,
82  // Use shallowRef for state (default: true)
83  shallow: true,
84  // Throw errors instead of catching them (default: false)
85  throwError: false,
86  // Called when promise resolves
87  onSuccess(data) {
88    console.log('Success:', data)
89  },
90  // Called when promise rejects
91  onError(error) {
92    console.error('Error:', error)
93  },
94})
95```
96 
97## Type Declarations
98 
99```ts
100export interface UseAsyncStateReturnBase<
101  Data,
102  Params extends any[],
103  Shallow extends boolean,
104> {
105  state: Shallow extends true ? Ref<Data> : Ref<UnwrapRef<Data>>
106  isReady: Ref<boolean>
107  isLoading: Ref<boolean>
108  error: Ref<unknown>
109  execute: (delay?: number, ...args: Params) => Promise<Data | undefined>
110  executeImmediate: (...args: Params) => Promise<Data | undefined>
111}
112export type UseAsyncStateReturn<
113  Data,
114  Params extends any[],
115  Shallow extends boolean,
116> = UseAsyncStateReturnBase<Data, Params, Shallow> &
117  PromiseLike<UseAsyncStateReturnBase<Data, Params, Shallow>>
118export interface UseAsyncStateOptions<Shallow extends boolean, D = any> {
119  /**
120   * Delay for the first execution of the promise when "immediate" is true. In milliseconds.
121   *
122   * @default 0
123   */
124  delay?: number
125  /**
126   * Execute the promise right after the function is invoked.
127   * Will apply the delay if any.
128   *
129   * When set to false, you will need to execute it manually.
130   *
131   * @default true
132   */
133  immediate?: boolean
134  /**
135   * Callback when error is caught.
136   */
137  onError?: (e: unknown) => void
138  /**
139   * Callback when success is caught.
140   * @param {D} data
141   */
142  onSuccess?: (data: D) => void
143  /**
144   * Sets the state to initialState before executing the promise.
145   *
146   * This can be useful when calling the execute function more than once (for
147   * example, to refresh data). When set to false, the current state remains
148   * unchanged until the promise resolves.
149   *
150   * @default true
151   */
152  resetOnExecute?: boolean
153  /**
154   * Use shallowRef.
155   *
156   * @default true
157   */
158  shallow?: Shallow
159  /**
160   *
161   * An error is thrown when executing the execute function
162   *
163   * @default false
164   */
165  throwError?: boolean
166}
167/**
168 * Reactive async state. Will not block your setup function and will trigger changes once
169 * the promise is ready.
170 *
171 * @see https://vueuse.org/useAsyncState
172 * @param promise         The promise / async function to be resolved
173 * @param initialState    The initial state, used until the first evaluation finishes
174 * @param options
175 */
176export declare function useAsyncState<
177  Data,
178  Params extends any[] = any[],
179  Shallow extends boolean = true,
180>(
181  promise: Promise<Data> | ((...args: Params) => Promise<Data>),
182  initialState: MaybeRef<Data>,
183  options?: UseAsyncStateOptions<Shallow, Data>,
184): UseAsyncStateReturn<Data, Params, Shallow>
185```
186