Skip to content

useAsyncState

Category
Export Size
930 B
Last Changed
3 weeks ago

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>

Source

SourceDemoDocs

Contributors

Anthony Fu
丶远方
Anthony Fu
Flamenco
machete
David Gonzalez
Robin
James Garbutt
Robin
Joris Gallot
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

v13.4.0 on
82740 - feat: add executeImmediate with the same type as the promise fn (#4716)
v12.1.0 on
4d0a7 - fix: use ShallowRef instead of Ref type (#4294)
v12.0.0-beta.1 on
0a9ed - feat!: drop Vue 2 support, optimize bundles and clean up (#4349)
v10.1.0 on
d4db0 - feat: add support directly await (#3004)
v10.0.0-beta.1 on
b636f - fix: fix toThrowError error type (#2898)

Released under the MIT License.

Build smarter with AI
Become an AIDD Insider
Secure early access + the best pricing & perks we'll ever offer. 24H only
Get notified
03
days
:
10
hours
:
13
minutes
:
22
seconds
: