Skip to content
On this page

useAsyncState

Category
Export Size
1.04 kB
Last Changed
4 weeks ago

Reactive async state. Will not block your setup function and will trigger changes once the promise is ready.

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

Source

SourceDemoDocs

Contributors

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

Changelog

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)
v8.9.2 on 7/12/2022
24ede - fix!: rename type AsyncStateOptions to UseAsyncStateOptions (#1809)
v8.4.0 on 5/3/2022
a8fd6 - fix: isLoading not reset (#1518)
v7.5.4 on 1/21/2022
3c384 - fix(types): do not use ShallowRef, close #1151
v7.5.3 on 1/5/2022
247cc - fix: improve types (#1119)
v7.5.0 on 12/31/2021
f0b96 - feat: add property isLoading (#1116)
v7.3.0 on 12/12/2021
b9952 - feat: add option for choosing shallowRef or ref (#1040)
v7.1.2 on 11/26/2021
6661a - fix: optional argument of execute (#972)

Released under the MIT License.