useAsyncFn

A React Hook to run async functions with extra loading state that indicates whether the promise is pending.

Demo

Click to mock fetch, and check the loading state.

Source
Loading:
false
Value:
click to fetch

Usage

See API for more details.

Source

Click links below to view source on GitHub.

API

const {
  run, loading, value, error,
  refresh, cancel, mutate, params
} = useAsyncFn(asyncFn, options)

AsyncFn

A function that returns a promise.

Options

export interface UseAsyncFnOptions<T extends AnyFunc, D = Awaited<ReturnType<T>>, E = any> {
  /**
   * Initial data to be used as the initial value
   *
   * @defaultValue undefined
   */
  initialValue?: D
  /**
   * Initial parameters passed to fetcher when first mount
   *
   * @defaultValue []
   */
  initialParams?: Gettable<Promisable<Parameters<T> | []>>
  /**
   * whether to run the async function immediately on component mount
   *
   * @defaultValue false
   */
  immediate?: boolean
  /**
   * whether to clear the value before running the function
   *
   * @defaultValue false
   */
  clearBeforeRun?: boolean
  /**
   * whether to cancel the async function when the component is unmounted
   *
   * @defaultValue true
   */
  cancelOnUnmount?: boolean
  /**
   * a function to run when the async function throws an error
   *
   * @defaultValue undefined
   */
  onError?: (error: E | undefined, params: Parameters<T> | []) => void
  /**
   * a function to run before the async function
   *
   * @defaultValue undefined
   */
  onBefore?: (value: D | undefined, params: Parameters<T> | []) => void
  /**
   * a function to run after the async function
   *
   * @defaultValue undefined
   */
  onSuccess?: (value: D, params: Parameters<T> | []) => void
  /**
   * a function to run after the async function
   *
   * @defaultValue undefined
   */
  onFinally?: (value: D | undefined, params: Parameters<T> | []) => void
  /**
   * a function to run when the async function is cancelled
   *
   * @defaultValue undefined
   */
  onCancel?: (value: D | undefined, params: Parameters<T> | []) => void
  /**
   * a function to run when the value is mutated
   *
   * @defaultValue undefined
   */
  onMutate?: (value: D | undefined, params: Parameters<T> | []) => void
  /**
   * a function to run when the value is refreshed
   *
   * @defaultValue undefined
   */
  onRefresh?: (value: D | undefined, params: Parameters<T> | []) => void
  /**
   * Custom cache comparison function, true means the cache is the same
   *
   * @defaultValue shallowEqual
   */
  compare?: (prevData: D | undefined, nextData: D | undefined) => boolean
}

Returns

export type UseAsyncFnMutateAction<D, P> =
  | [D | undefined]
  | [D | undefined, P | undefined]
  | [(prevData: D | undefined, preParams?: P) => [D, P | undefined]]

export interface UseAsyncFnReturns<T extends AnyFunc, D = Awaited<ReturnType<T>>, E = any> {
  /**
   * a function to run the async function
   */
  run: T
  /**
   * a function to refresh the async function
   */
  refresh: (params?: Parameters<T> | []) => Promise<D | undefined>
  /**
   * a function to cancel the async function
   */
  cancel: () => void
  /**
   * manually set the value
   */
  mutate: (...actions: UseAsyncFnMutateAction<D | undefined, Parameters<T> | []>) => void
  /**
   * whether the async function is loading
   */
  loading: boolean
  /**
   * the error thrown by the async function
   */
  error: E | undefined
  /**
   * the value returned by the async function
   */
  value: D | undefined
  /**
   * the parameters passed to the async function
   */
  params: Parameters<T> | []
}