#useAsyncFn
Tags:
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> | []
}
ON THIS PAGE