Skip to content

useAsyncState ​

Category
Export Size
1.17 kB
Last Changed
last year

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: false
Loading: true
{}

Usage ​

ts
import axios from 'axios'
import { useAsyncState } from '@vueuse/core'

const { state, isReady, isLoading } = useAsyncState(
  axios
    .get('https://jsonplaceholder.typicode.com/todos/1')
    .then(t => t.data),
  { id: null },
)

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>
}
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 executing the promise. 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[] = [],
  Shallow extends boolean = true,
>(
  promise: Promise<Data> | ((...args: Params) => Promise<Data>),
  initialState: Data,
  options?: UseAsyncStateOptions<Shallow, Data>,
): UseAsyncStateReturn<Data, Params, Shallow>

Source ​

Source • Demo • Docs

Contributors ​

Anthony Fu
丶远方
Flamenco
machete
Jules Raffoux
hfutsora
Brain777777
Mao Mr
Jelf
Sergey Shumov
lsdsjy
IIFelix
Alex Francev
webfansplz
Shinigami
Shahar Kosti
Alex Kozack
ordago
Jacob Clevenger
Antério Vieira

Changelog ​

v10.1.0 on 4/22/2023
d4db0 - feat: add support directly await (#3004)
v10.0.0-beta.1 on 3/23/2023
b636f - fix: fix toThrowError error type (#2898)
v9.13.0 on 2/18/2023
b4c63 - feat: get a promise function parameter type declaration (#2765)
v9.9.0 on 12/23/2022
ed64f - feat: add onSuccess callbacks (#2562)
v9.0.0-beta.2 on 7/24/2022
837b6 - feat: add throwError option (#1975)

Released under the MIT License.