A function that accepts a Redux action type string and a callback function that should return a promise. It generates promise lifecycle action types based on the action type prefix that you pass in, and returns a thunk action creator that will run the promise callback and dispatch the lifecycle actions based on the returned promise.
This abstracts the standard recommended approach for handling async request lifecycles.
It does not generate any reducer functions, since it does not know what data you're fetching, how you want to track loading state, or how the data you return needs to be processed. You should write your own reducer logic that handles these actions, with whatever loading state and processing logic is appropriate for your own app.
Sample usage:
import { createAsyncThunk, createSlice } from '@reduxjs/toolkit'
import { userAPI } from './userAPI'
// First, create the thunk
const fetchUserById = createAsyncThunk(
'users/fetchByIdStatus',
async (userId, thunkAPI) => {
const response = await userAPI.fetchById(userId)
return response.data
}
)
// Then, handle actions in your reducers:
const usersSlice = createSlice({
name: 'users',
initialState: { entities: [], loading: 'idle' },
reducers: {
// standard reducer logic, with auto-generated action types per reducer
},
extraReducers: {
// Add reducers for additional action types here, and handle loading state as needed
[fetchUserById.fulfilled]: (state, action) => {
// Add user to the state array
state.entities.push(action.payload)
},
},
})
// Later, dispatch the thunk as needed in the app
dispatch(fetchUserById(123))
Parameters
createAsyncThunk accepts three parameters: a string action type value, a payloadCreator callback, and an options object.
type
A string that will be used to generate additional Redux action type constants, representing the lifecycle of an async request:
For example, a type argument of 'users/requestStatus' will generate these action types:
pending: 'users/requestStatus/pending'
fulfilled: 'users/requestStatus/fulfilled'
rejected: 'users/requestStatus/rejected'
payloadCreator
A callback function that should return a promise containing the result of some asynchronous logic. It may also return a value synchronously. If there is an error, it should either return a rejected promise containing an Error instance or a plain value such as a descriptive error message or otherwise a resolved promise with a RejectWithValue argument as returned by the thunkAPI.rejectWithValue function.
The payloadCreator function can contain whatever logic you need to calculate an appropriate result. This could include a standard AJAX data fetch request, multiple AJAX calls with the results combined into a final value, interactions with React Native AsyncStorage, and so on.
The payloadCreator function will be called with two arguments:
arg: a single value, containing the first parameter that was passed to the thunk action creator when it was dispatched. This is useful for passing in values like item IDs that may be needed as part of the request. If you need to pass in multiple values, pass them together in an object when you dispatch the thunk, like dispatch(fetchUsers({status: 'active', sortBy: 'name'})).
thunkAPI: an object containing all of the parameters that are normally passed to a Redux thunk function, as well as additional options:
dispatch: the Redux store dispatch method
getState: the Redux store getState method
extra: the "extra argument" given to the thunk middleware on setup, if available
requestId: a unique string ID value that was automatically generated to identify this request sequence
rejectWithValue(value, [meta]): rejectWithValue is a utility function that you can return (or throw) in your action creator to return a rejected response with a defined payload and meta. It will pass whatever value you give it and return it in the payload of the rejected action. If you also pass in a meta, it will be merged with the existing rejectedAction.meta.
fulfillWithValue(value, meta): fulfillWithValue is a utility function that you can return in your action creator to fulfill with a value while having the ability of adding to fulfilledAction.meta.
The logic in the payloadCreator function may use any of these values as needed to calculate the result.
Options
An object with the following optional fields:
dispatchConditionRejection: if condition() returns false, the default behavior is that no actions will be dispatched at all. If you still want a "rejected" action to be dispatched when the thunk was canceled, set this flag to true.
serializeError(error: unknown) => any to replace the internal miniSerializeError method with your own serialization logic.
getPendingMeta({ arg, requestId }, { getState, extra }): any: a function to create an object that will be merged into the pendingAction.meta field.
Return Value
createAsyncThunk returns a standard Redux thunk action creator. The thunk action creator function will have plain action creators for the pending, fulfilled, and rejected cases attached as nested fields.
Using the fetchUserById example above, createAsyncThunk will generate four functions:
fetchUserById, the thunk action creator that kicks off the async payload callback you wrote
fetchUserById.pending, an action creator that dispatches an 'users/fetchByIdStatus/pending' action
fetchUserById.fulfilled, an action creator that dispatches an 'users/fetchByIdStatus/fulfilled' action
fetchUserById.rejected, an action creator that dispatches an 'users/fetchByIdStatus/rejected' action
When dispatched, the thunk will:
dispatch the pending action
call the payloadCreator callback and wait for the returned promise to settle
when the promise settles:
if the promise resolved successfully, dispatch the fulfilled action with the promise value as action.payload
if the promise resolved with a rejectWithValue(value) return value, dispatch the rejected action with the value passed into action.payload and 'Rejected' as action.error.message
if the promise failed and was not handled with rejectWithValue, dispatch the rejected action with a serialized version of the error value as action.error
Return a fulfilled promise containing the final dispatched action (either the fulfilled or rejected action object)
Thunks may return a value when dispatched. A common use case is to return a promise from the thunk, dispatch the thunk from a component, and then wait for the promise to resolve before doing additional work:
const onClick = () => {
dispatch(fetchUserById(userId)).then(() => {
// do additional work
})
}
The thunks generated by createAsyncThunkwill always return a resolved promise with either the fulfilled action object or rejected action object inside, as appropriate.
The calling logic may wish to treat these actions as if they were the original promise contents. Redux Toolkit exports an unwrapResult function that can be used to extract the payload of a fulfilled action or to throw either the error or, if available, payload created by rejectWithValue from a rejected action:
import { unwrapResult } from '@reduxjs/toolkit'
// in the component
const onClick = () => {
dispatch(fetchUserById(userId))
.then(unwrapResult)
.then((originalPromiseResult) => {})
.catch((rejectedValueOrSerializedError) => {})
}
Checking Errors After Dispatching
Note that this means a failed request or error in a thunk will never return a rejected promise. We assume that any failure is more of a handled error than an unhandled exception at this point. This is due to the fact that we want to prevent uncaught promise rejections for those who do not use the result of dispatch.
If your component needs to know if the request failed, use unwrapResult and handle the re-thrown error accordingly.
Handling Thunk Errors
When your payloadCreator returns a rejected promise (such as a thrown error in an async function), the thunk will dispatch a rejected action containing an automatically-serialized version of the error as action.error. However, to ensure serializability, everything that does not match the SerializedError interface will have been removed from it:
If you need to customize the contents of the rejected action, you should catch any errors yourself, and then return a new value using the thunkAPI.rejectWithValue utility. Doing return rejectWithValue(errorPayload) will cause the rejected action to use that value as action.payload.
The rejectWithValue approach should also be used if your API response "succeeds", but contains some kind of additional error details that the reducer should know about. This is particularly common when expecting field-level validation errors from an API.
const updateUser = createAsyncThunk(
'users/update',
async (userData, { rejectWithValue }) => {
const { id, ...fields } = userData
try {
const response = await userAPI.updateById(id, fields)
return response.data.user
} catch (err) {
// Use `err.response.data` as `action.payload` for a `rejected` action,
// by explicitly returning it using the `rejectWithValue()` utility
return rejectWithValue(err.response.data)
}
}
)
Cancellation
Canceling Before Execution
If you need to cancel a thunk before the payload creator is called, you may provide a condition callback as an option after the payload creator. The callback will receive the thunk argument and an object with {getState, extra} as parameters, and use those to decide whether to continue or not. If the execution should be canceled, the condition callback should return a literal false value:
If condition() returns false, the default behavior is that no actions will be dispatched at all. If you still want a "rejected" action to be dispatched when the thunk was canceled, pass in {condition, dispatchConditionRejection: true}.
Canceling While Running
If you want to cancel your running thunk before it has finished, you can use the abort method of the promise returned by dispatch(fetchUserById(userId)).
A real-life example of that would look like this:
// file: store.ts noEmit
import { configureStore, Reducer } from '@reduxjs/toolkit'
import { useDispatch } from 'react-redux'
declare const reducer: Reducer<{}>
const store = configureStore({ reducer })
export const useAppDispatch = () => useDispatch<typeof store.dispatch>()
// file: slice.ts noEmit
import { createAsyncThunk } from '@reduxjs/toolkit'
export const fetchUserById = createAsyncThunk(
'fetchUserById',
(userId: string) => {
/* ... */
}
)
// file: MyComponent.ts
import { fetchUserById } from './slice'
import { useAppDispatch } from './store'
import React from 'react'
function MyComponent(props: { userId: string }) {
const dispatch = useAppDispatch()
React.useEffect(() => {
// Dispatching the thunk returns a promise
const promise = dispatch(fetchUserById(props.userId))
return () => {
// `createAsyncThunk` attaches an `abort()` method to the promise
promise.abort()
}
}, [props.userId])
}
After a thunk has been cancelled this way, it will dispatch (and return) a "thunkName/rejected" action with an AbortError on the error property. The thunk will not dispatch any further actions.
Additionally, your payloadCreator can use the AbortSignal it is passed via thunkAPI.signal to actually cancel a costly asynchronous action.
The fetch api of modern browsers already comes with support for an AbortSignal:
You can use the signal.aborted property to regularly check if the thunk has been aborted and in that case stop costly long-running work:
import { createAsyncThunk } from '@reduxjs/toolkit'
const readStream = createAsyncThunk(
'readStream',
async (stream: ReadableStream, { signal }) => {
const reader = stream.getReader()
let done = false
let result = ''
while (!done) {
if (signal.aborted) {
throw new Error('stop the work, this has been aborted!')
}
const read = await reader.read()
result += read.value
done = read.done
}
return result
}
)
Listening for Abort Events
You can also call signal.addEventListener('abort', callback) to have logic inside the thunk be notified when promise.abort() was called. This can for example be used in conjunction with an axios CancelToken:
signal: an that may be used to see if another part of the app logic has marked this request as needing cancelation.
condition(arg, { getState, extra } ): boolean: a callback that can be used to skip execution of the payload creator and all action dispatches, if desired. See for a complete description.
idGenerator(): string: a function to use when generating the requestId for the request sequence. Defaults to use .
createAsyncThunk will generate three Redux action creators using : pending, fulfilled, and rejected. Each lifecycle action creator will be attached to the returned thunk action creator so that your reducer logic can reference the action types and respond to the actions when dispatched. Each action object will contain the current unique requestId and arg values under action.meta.
To handle these actions in your reducers, reference the action creators in createReducer or createSlice using either the object key notation or the "builder callback" notation. (Note that if you use TypeScript, you ):
